From f91dab4c07f206bc194e93ea4895903431e4da67 Mon Sep 17 00:00:00 2001 From: Aleksandar Vidakovic Date: Wed, 5 Aug 2026 10:30:56 +0200 Subject: [PATCH 01/11] FINERACT-2485: Standardize and harden idempotency --- build.gradle | 2 + .../command/async/AsyncCommandConstants.java | 30 ++++++++ .../command/async/AsyncCommandProperties.java | 4 +- .../AsyncCommandDispatcher.java | 31 +++++--- .../AsyncCommandAutoConfiguration.java | 7 +- .../command/audit/AuditCommandConstants.java | 15 +++- .../command/audit/AuditCommandProperties.java | 12 +++- .../check/AuditCommandPropertyCheck.java | 56 +++++++++++++++ .../audit/hook/AuditCommandHookAfter.java | 16 +++-- .../audit/hook/AuditCommandHookBefore.java | 19 +++-- .../audit/hook/AuditCommandHookError.java | 21 +++--- .../AuditCommandAutoConfiguration.java | 7 +- ...CommandPropertyCheckAutoConfiguration.java | 28 ++++++++ ...ot.autoconfigure.AutoConfiguration.imports | 3 +- .../resources/application-test.properties | 6 +- .../disruptor/DisruptorCommandConstants.java | 30 ++++++++ .../disruptor/DisruptorCommandProperties.java | 4 +- .../DisruptorCommandDispatcher.java | 36 +++++++--- .../DisruptorCommandAutoConfiguration.java | 7 +- fineract-command-idempotency/build.gradle | 72 +++++++++++++++++++ .../dependencies.gradle | 32 +++++++++ .../IdempotencyCommandConstants.java | 36 ++++++++++ .../IdempotencyCommandProperties.java | 54 ++++++++++++++ .../hook/IdempotencyCheckCommandHook.java | 68 ++++++++++++++++++ .../hook/IdempotencyKeyHeaderCommandHook.java | 52 ++++++++++++++ .../IdempotencyCommandAutoConfiguration.java | 34 +++++++++ ...ot.autoconfigure.AutoConfiguration.imports | 1 + .../command/jdbc/JdbcCommandConstants.java | 30 ++++++++ .../command/jdbc/JdbcCommandProperties.java | 4 +- .../starter/JdbcCommandAutoConfiguration.java | 7 +- .../command/jdbc/store/JdbcCommandStore.java | 51 +++++++------ ...sitory.java => JdbcCommandRepository.java} | 4 +- ...mandMapper.java => JdbcCommandMapper.java} | 4 +- ...JsonMapper.java => JsonCommandMapper.java} | 2 +- .../command/module-changelog-master.xml | 2 + .../parts/0003_idempotency_key_unique.xml | 43 +++++++++++ ...st.java => JdbcCommandRepositoryTest.java} | 10 +-- .../command/core/CommandConstants.java | 9 +++ .../fineract/command/core/CommandContext.java | 53 ++++++++++++++ .../command/core/CommandHookAfter.java | 2 +- .../command/core/CommandHookBefore.java | 4 +- .../command/core/CommandHookError.java | 4 +- .../command/core/CommandHookManager.java | 7 +- .../command/core/CommandProperties.java | 12 +++- .../fineract/command/core/CommandStore.java | 12 ++-- .../hook/ServletHeadersCommandHook.java | 36 +++------- .../command/hook/TimestampCommandHook.java | 11 +-- .../command/hook/UsernameCommandHook.java | 11 +-- .../DefaultCommandHookManager.java | 47 ++++++++++-- .../SynchronousCommandDispatcher.java | 21 ++++-- .../command/starter/CommandConfiguration.java | 10 ++- .../command/util/ServletHeaderUtil.java | 44 ++++++++++++ .../command/CommandSampleApiTest.java | 13 ++-- .../resources/application-test.properties | 6 +- .../en/chapters/architecture/idempotency.adoc | 2 + fineract-provider/dependencies.gradle | 1 + .../service/TemplateDomainServiceImpl.java | 3 - .../src/main/resources/application.properties | 21 ++++-- .../TemplateDomainServiceImplTest.java | 4 -- .../resources/application-test.properties | 12 ++-- settings.gradle | 1 + 61 files changed, 990 insertions(+), 196 deletions(-) create mode 100644 fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java create mode 100644 fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java create mode 100644 fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java create mode 100644 fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java create mode 100644 fineract-command-idempotency/build.gradle create mode 100644 fineract-command-idempotency/dependencies.gradle create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java create mode 100644 fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports create mode 100644 fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java rename fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/{CommandRepository.java => JdbcCommandRepository.java} (85%) rename fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/{CommandMapper.java => JdbcCommandMapper.java} (97%) rename fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/{CommandJsonMapper.java => JsonCommandMapper.java} (98%) create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml rename fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/{CommandRepositoryTest.java => JdbcCommandRepositoryTest.java} (89%) create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java diff --git a/build.gradle b/build.gradle index ab257152a0f..9d9d9dce398 100644 --- a/build.gradle +++ b/build.gradle @@ -33,6 +33,7 @@ buildscript { 'fineract-command-audit', 'fineract-command-async', 'fineract-command-disruptor', + 'fineract-command-idempotency', 'fineract-accounting', 'fineract-provider', 'fineract-branch', @@ -73,6 +74,7 @@ buildscript { 'fineract-command', 'fineract-command-jdbc', 'fineract-command-audit', + 'fineract-command-idempotency', 'fineract-accounting', 'fineract-provider', 'fineract-investor', diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java new file mode 100644 index 00000000000..8fd93a922a6 --- /dev/null +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.async; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class AsyncCommandConstants { + + private AsyncCommandConstants() {} + + public static final String COMMAND_ASYNC_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".async"; + public static final String COMMAND_ASYNC_PROPERTY_ENABLED = COMMAND_ASYNC_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_ASYNC_BASE_PACKAGE = "org.apache.fineract.command.async.implementation"; +} diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java index 832318ed96d..d1d5d7b348d 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.async; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import java.time.Duration; @@ -33,7 +35,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.async") +@ConfigurationProperties(prefix = COMMAND_ASYNC_PROPERTIES_PREFIX) public final class AsyncCommandProperties implements Serializable { @Serial diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java index 7999af97c5b..122f61a26f0 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java @@ -19,7 +19,9 @@ package org.apache.fineract.command.async.implementation; import static java.util.Objects.requireNonNull; -import static java.util.concurrent.TimeUnit.SECONDS; +import static java.util.concurrent.TimeUnit.MILLISECONDS; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTY_ENABLED; +import static org.apache.fineract.command.core.CommandState.PROCESSED; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; @@ -27,7 +29,9 @@ import java.util.function.Supplier; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.async.AsyncCommandProperties; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.core.CommandHandlerManager; import org.apache.fineract.command.core.CommandHookManager; @@ -38,34 +42,45 @@ @Slf4j @RequiredArgsConstructor @Component -@ConditionalOnProperty(value = "fineract.command.async.enabled", havingValue = "true") +@ConditionalOnProperty(value = COMMAND_ASYNC_PROPERTY_ENABLED, havingValue = "true") public class AsyncCommandDispatcher implements CommandDispatcher { private final CommandHandlerManager handlerManager; private final CommandHookManager hookManager; + private final AsyncCommandProperties properties; @Override public Supplier dispatch(final Command command) { requireNonNull(command, "Command must not be null"); + final var ctx = CommandContext.builder().command(command).build(); + CompletableFuture future = CompletableFuture.supplyAsync(() -> { - hookManager.before(command); + hookManager.before(ctx); + + if (ctx.isSkipExecution()) { + return ctx.getResponse(); + } RES response = handlerManager.handle(command); - hookManager.after(command, response); + ctx.setResponse(response); + ctx.setState(PROCESSED); - return response; + hookManager.after(ctx); + + return ctx.getResponse(); }).whenComplete((response, t) -> { if (t != null) { - hookManager.error(command, t); + ctx.setError(t); + + hookManager.error(ctx); } }); return () -> { try { - // TODO: make this configurable - return future.get(3, SECONDS); + return future.get(properties.getTimeout().toMillis(), MILLISECONDS); } catch (InterruptedException | ExecutionException | TimeoutException e) { throw new RuntimeException(e); } diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java index d4410fb07fc..2f112586b5b 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.async.starter; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_BASE_PACKAGE; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTY_ENABLED; + import org.apache.fineract.command.async.AsyncCommandProperties; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -26,6 +29,6 @@ @AutoConfiguration @EnableConfigurationProperties(AsyncCommandProperties.class) -@ComponentScan("org.apache.fineract.command.async.implementation") -@ConditionalOnProperty(value = "fineract.command.async.enabled", havingValue = "true") +@ComponentScan(COMMAND_ASYNC_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_ASYNC_PROPERTY_ENABLED, havingValue = "true") public class AsyncCommandAutoConfiguration {} diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java index 5ba7b115822..9dc48376e58 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java @@ -18,11 +18,20 @@ */ package org.apache.fineract.command.audit; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + public final class AuditCommandConstants { private AuditCommandConstants() {} - public static final int COMMAND_HOOK_AUDIT_BEFORE = 20; - public static final int COMMAND_HOOK_AUDIT_AFTER = 20; - public static final int COMMAND_HOOK_AUDIT_ERROR = 20; + public static final String COMMAND_AUDIT_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".audit"; + public static final String COMMAND_AUDIT_PROPERTY_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-pre-enabled"; + public static final String COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-post-enabled"; + public static final String COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-error-enabled"; + public static final String COMMAND_AUDIT_HOOK_BASE_PACKAGE = "org.apache.fineract.command.audit.hook"; + public static final String COMMAND_AUDIT_HOOK_CHECK_PACKAGE = COMMAND_AUDIT_HOOK_BASE_PACKAGE + ".check"; + public static final int COMMAND_AUDIT_HOOK_BEFORE = 30; + public static final int COMMAND_AUDIT_HOOK_AFTER = 30; + public static final int COMMAND_AUDIT_HOOK_ERROR = 30; } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java index 12995780098..ac5eb45393e 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.audit; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import lombok.AllArgsConstructor; @@ -32,12 +34,18 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.audit") +@ConfigurationProperties(prefix = COMMAND_AUDIT_PROPERTIES_PREFIX) public final class AuditCommandProperties implements Serializable { @Serial private static final long serialVersionUID = 1L; @Builder.Default - private Boolean enabled = false; + private Boolean enabled = true; + @Builder.Default + private Boolean hookPreEnabled = true; + @Builder.Default + private Boolean hookPostEnabled = true; + @Builder.Default + private Boolean hookErrorEnabled = true; } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java new file mode 100644 index 00000000000..c97b4c1b129 --- /dev/null +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java @@ -0,0 +1,56 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.audit.check; + +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED; + +import jakarta.annotation.PostConstruct; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.core.env.Environment; +import org.springframework.stereotype.Component; + +@Slf4j +@RequiredArgsConstructor +@Component +final class AuditCommandPropertyCheck { + + private final Environment environment; + + @PostConstruct + public void check() { + if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED)) { + log.info("Audit pre command hook enabled."); + } else { + log.warn("Audit pre command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); + } + if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED)) { + log.info("Audit post command hook enabled."); + } else { + log.warn("Audit post command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); + } + if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED)) { + log.info("Audit error command hook enabled."); + } else { + log.warn("Audit error command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); + } + } +} diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java index 529ed034961..d315741c672 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java @@ -18,13 +18,13 @@ */ package org.apache.fineract.command.audit.hook; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_HOOK_AUDIT_AFTER; -import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_AFTER; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookAfter; import org.apache.fineract.command.core.CommandStore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -34,20 +34,22 @@ @Slf4j @RequiredArgsConstructor @Component -@Order(COMMAND_HOOK_AUDIT_AFTER) -@ConditionalOnProperty(value = "fineract.command.hooks.audit-post", havingValue = "true") +@Order(COMMAND_AUDIT_HOOK_AFTER) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, havingValue = "true", matchIfMissing = false) final class AuditCommandHookAfter implements CommandHookAfter { private final CommandStore store; @Override - public void onAfter(Command command, Object response) { + public void onAfter(CommandContext ctx) { final var now = Instant.now(); + var command = ctx.getCommand(); + command.setExecutedByUsername(command.getInitiatedByUsername()); command.setUpdatedAt(now); command.setExecutedAt(now); - store.store(command, response, PROCESSED); + store.store(ctx); } } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java index 524f47537e0..6b303c46a52 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java @@ -18,13 +18,14 @@ */ package org.apache.fineract.command.audit.hook; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_HOOK_AUDIT_BEFORE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_BEFORE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED; import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandStore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -34,20 +35,24 @@ @Slf4j @RequiredArgsConstructor @Component -@Order(COMMAND_HOOK_AUDIT_BEFORE) -@ConditionalOnProperty(value = "fineract.command.hooks.audit-pre", havingValue = "true") -final class AuditCommandHookBefore implements CommandHookBefore { +@Order(COMMAND_AUDIT_HOOK_BEFORE) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED, havingValue = "true") +final class AuditCommandHookBefore implements CommandHookBefore { private final CommandStore store; @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { final var now = Instant.now(); + var command = ctx.getCommand(); + command.setExecutedByUsername(command.getInitiatedByUsername()); command.setUpdatedAt(now); command.setExecutedAt(now); - store.store(command, null, UNDER_PROCESSING); + ctx.setState(UNDER_PROCESSING); + + store.store(ctx); } } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java index fe1d2b6376a..7179b3e8eb3 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java @@ -18,13 +18,14 @@ */ package org.apache.fineract.command.audit.hook; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_HOOK_AUDIT_ERROR; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_ERROR; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED; import static org.apache.fineract.command.core.CommandState.ERROR; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookError; import org.apache.fineract.command.core.CommandStore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -34,20 +35,24 @@ @Slf4j @RequiredArgsConstructor @Component -@Order(COMMAND_HOOK_AUDIT_ERROR) -@ConditionalOnProperty(value = "fineract.command.hooks.audit-error", havingValue = "true") -final class AuditCommandHookError implements CommandHookError { +@Order(COMMAND_AUDIT_HOOK_ERROR) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, havingValue = "true") +final class AuditCommandHookError implements CommandHookError { private final CommandStore store; @Override - public void onError(Command command, Throwable error) { + public void onError(CommandContext ctx) { final var now = Instant.now(); - command.setError(error.getMessage()); + ctx.setState(ERROR); + + var command = ctx.getCommand(); + + command.setError(ctx.getError().getMessage()); command.setUpdatedAt(now); command.setExecutedAt(now); - store.store(command, null, ERROR); + store.store(ctx); } } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java index 7b186c6c4a5..366e94a3b1a 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.audit.starter; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_BASE_PACKAGE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_ENABLED; + import org.apache.fineract.command.audit.AuditCommandProperties; import org.apache.fineract.command.core.CommandProperties; import org.springframework.boot.autoconfigure.AutoConfiguration; @@ -27,6 +30,6 @@ @AutoConfiguration @EnableConfigurationProperties({ CommandProperties.class, AuditCommandProperties.class }) -@ComponentScan("org.apache.fineract.command.audit.hook") -@ConditionalOnProperty(value = "fineract.command.audit.enabled", havingValue = "true") +@ComponentScan(COMMAND_AUDIT_HOOK_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_ENABLED, havingValue = "true") public class AuditCommandAutoConfiguration {} diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java new file mode 100644 index 00000000000..8eb8709c78f --- /dev/null +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java @@ -0,0 +1,28 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.audit.starter; + +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_CHECK_PACKAGE; + +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.context.annotation.ComponentScan; + +@AutoConfiguration +@ComponentScan(COMMAND_AUDIT_HOOK_CHECK_PACKAGE) +public class AuditCommandPropertyCheckAutoConfiguration {} diff --git a/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports index 56b407045f3..6041b23e1fe 100644 --- a/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports +++ b/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports @@ -1 +1,2 @@ -org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration \ No newline at end of file +org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration +org.apache.fineract.command.audit.starter.AuditCommandPropertyCheckAutoConfiguration \ No newline at end of file diff --git a/fineract-command-audit/src/test/resources/application-test.properties b/fineract-command-audit/src/test/resources/application-test.properties index e160de083a8..5611a2cb03b 100644 --- a/fineract-command-audit/src/test/resources/application-test.properties +++ b/fineract-command-audit/src/test/resources/application-test.properties @@ -21,6 +21,6 @@ debug=true fineract.command.enabled=true fineract.command.audit.enabled=true -fineract.command.hooks.audit-pre=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE:true} -fineract.command.hooks.audit-post=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST:true} -fineract.command.hooks.audit-error=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR:true} +fineract.command.audit.hook-pre-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE_ENABLED:true} +fineract.command.audit.hook-post-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED:true} +fineract.command.audit.hook-error-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR_ENABLED:true} diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java new file mode 100644 index 00000000000..f478fcc93f8 --- /dev/null +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.disruptor; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class DisruptorCommandConstants { + + private DisruptorCommandConstants() {} + + public static final String COMMAND_DISRUPTOR_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".disruptor"; + public static final String COMMAND_DISRUPTOR_PROPERTY_ENABLED = COMMAND_DISRUPTOR_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_DISRUPTOR_BASE_PACKAGE = "org.apache.fineract.command.disruptor.implementation"; +} diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java index 130990a8564..aeda9dca444 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.disruptor; +import static org.apache.fineract.command.disruptor.DisruptorCommandConstants.COMMAND_DISRUPTOR_PROPERTIES_PREFIX; + import com.lmax.disruptor.dsl.ProducerType; import java.io.Serial; import java.io.Serializable; @@ -33,7 +35,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.disruptor") +@ConfigurationProperties(prefix = COMMAND_DISRUPTOR_PROPERTIES_PREFIX) public final class DisruptorCommandProperties implements Serializable { @Serial diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java index 59f48211ad0..102164915e0 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java @@ -19,6 +19,8 @@ package org.apache.fineract.command.disruptor.implementation; import static java.util.Objects.requireNonNull; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.disruptor.DisruptorCommandConstants.COMMAND_DISRUPTOR_PROPERTY_ENABLED; import com.lmax.disruptor.EventHandler; import com.lmax.disruptor.dsl.Disruptor; @@ -31,6 +33,7 @@ import lombok.Setter; import lombok.extern.slf4j.Slf4j; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.core.CommandHandlerManager; import org.apache.fineract.command.core.CommandHookManager; @@ -43,7 +46,7 @@ @Slf4j @RequiredArgsConstructor @Component -@ConditionalOnProperty(value = "fineract.command.disruptor.enabled", havingValue = "true") +@ConditionalOnProperty(value = COMMAND_DISRUPTOR_PROPERTY_ENABLED, havingValue = "true") @SuppressWarnings({ "unchecked", "rawtypes" }) public class DisruptorCommandDispatcher implements CommandDispatcher, Closeable { @@ -53,7 +56,7 @@ public class DisruptorCommandDispatcher implements CommandDispatcher, Closeable public Supplier dispatch(Command command) { requireNonNull(command, "Command must not be null"); - CommandEvent processedEvent = next(command); + CommandEvent processedEvent = next(CommandContext.builder().command(command).build()); var future = processedEvent.getFuture(); @@ -71,13 +74,13 @@ void onStartup() { } @SuppressWarnings({ "unchecked" }) - private CommandEvent next(Command command) { + private CommandEvent next(CommandContext ctx) { var ringBuffer = disruptor.getRingBuffer(); var sequenceId = ringBuffer.next(); CommandEvent event = ringBuffer.get(sequenceId); - event.setCommand(command); + event.setContext(ctx); ringBuffer.publish(sequenceId); return event; @@ -87,7 +90,7 @@ private CommandEvent next(Command command) { @Setter public static class CommandEvent { - private Command command; + private CommandContext context; private CompletableFuture future = new CompletableFuture<>(); } @@ -100,20 +103,31 @@ public static class CompleteableCommandEventHandler implements EventHandler()); } } } diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/starter/DisruptorCommandAutoConfiguration.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/starter/DisruptorCommandAutoConfiguration.java index 8021702d3aa..3c86e1fa183 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/starter/DisruptorCommandAutoConfiguration.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/starter/DisruptorCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.disruptor.starter; +import static org.apache.fineract.command.disruptor.DisruptorCommandConstants.COMMAND_DISRUPTOR_BASE_PACKAGE; +import static org.apache.fineract.command.disruptor.DisruptorCommandConstants.COMMAND_DISRUPTOR_PROPERTY_ENABLED; + import org.apache.fineract.command.disruptor.DisruptorCommandProperties; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -27,7 +30,7 @@ @AutoConfiguration @EnableConfigurationProperties(DisruptorCommandProperties.class) -@ComponentScan("org.apache.fineract.command.disruptor.implementation") +@ComponentScan(COMMAND_DISRUPTOR_BASE_PACKAGE) @Import({ DisruptorCommandConfiguration.class }) -@ConditionalOnProperty(value = "fineract.command.disruptor.enabled", havingValue = "true") +@ConditionalOnProperty(value = COMMAND_DISRUPTOR_PROPERTY_ENABLED, havingValue = "true") public class DisruptorCommandAutoConfiguration {} diff --git a/fineract-command-idempotency/build.gradle b/fineract-command-idempotency/build.gradle new file mode 100644 index 00000000000..6e94f90cc23 --- /dev/null +++ b/fineract-command-idempotency/build.gradle @@ -0,0 +1,72 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +description = 'Fineract Command Idempotency' + +apply plugin: 'java' +apply plugin: 'eclipse' + +configurations { + asciidoctorExtensions + providedRuntime // needed for Spring Boot executable WAR + providedCompile + compile() { + exclude module: 'hibernate-entitymanager' + exclude module: 'hibernate-validator' + exclude module: 'activation' + exclude module: 'bcmail-jdk14' + exclude module: 'bcprov-jdk14' + exclude module: 'bctsp-jdk14' + exclude module: 'c3p0' + exclude module: 'stax-api' + exclude module: 'jaxb-api' + exclude module: 'jaxb-impl' + exclude module: 'jboss-logging' + exclude module: 'itext-rtf' + exclude module: 'classworlds' + } + runtime +} + +apply from: 'dependencies.gradle' + +// Configuration for the modernizer plugin +// https://github.com/andygoossens/gradle-modernizer-plugin +modernizer { + ignoreClassNamePatterns = [ + '.*AbstractPersistableCustom', + '.*EntityTables', + '.*domain.*' + ] +} + +// If we are running Gradle within Eclipse to enhance classes with OpenJPA, +// set the classes directory to point to Eclipse's default build directory +if (project.hasProperty('env') && project.getProperty('env') == 'eclipse') { + sourceSets.main.java.outputDir = new File(rootProject.projectDir, "fineract-command-idempotency/bin/main") +} + +if (!(project.hasProperty('env') && project.getProperty('env') == 'dev')) { + sourceSets { + test { + java { + exclude '**/core/boot/tests/**' + } + } + } +} diff --git a/fineract-command-idempotency/dependencies.gradle b/fineract-command-idempotency/dependencies.gradle new file mode 100644 index 00000000000..9bb49133333 --- /dev/null +++ b/fineract-command-idempotency/dependencies.gradle @@ -0,0 +1,32 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +dependencies { + implementation( + project(path: ':fineract-command'), + ) + + implementation( + 'org.springframework.boot:spring-boot-starter', + + 'org.apache.commons:commons-lang3', + ) + compileOnly 'org.projectlombok:lombok' + annotationProcessor 'org.projectlombok:lombok' +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java new file mode 100644 index 00000000000..3d544da6783 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java @@ -0,0 +1,36 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class IdempotencyCommandConstants { + + private IdempotencyCommandConstants() {} + + public static final String COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".idempotency"; + public static final String COMMAND_IDEMPOTENCY_PROPERTY_ENABLED = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + + ".hook-key-header-pre"; + public static final String COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + ".hook-check-pre"; + public static final String COMMAND_IDEMPOTENCY_PROPERTY_KEY_HEADER_NAME = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + ".key-header-name"; + public static final String COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE = "org.apache.fineract.command.idempotency.hook"; + public static final int COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE = 20; + public static final int COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE = 21; +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java new file mode 100644 index 00000000000..207390b1b3a --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java @@ -0,0 +1,54 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX; + +import java.io.Serial; +import java.io.Serializable; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Data; +import lombok.NoArgsConstructor; +import lombok.experimental.FieldNameConstants; +import org.springframework.boot.context.properties.ConfigurationProperties; + +@Builder +@Data +@NoArgsConstructor +@AllArgsConstructor +@FieldNameConstants +@ConfigurationProperties(prefix = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX) +public final class IdempotencyCommandProperties implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + @Builder.Default + private Boolean enabled = false; + + @Builder.Default + private Boolean hookKeyHeaderPre = false; + + @Builder.Default + private Boolean hookCheckPre = false; + + @Builder.Default + private String keyHeaderName = "Idempotency-Key"; +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java new file mode 100644 index 00000000000..f1d0e8b5eaf --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -0,0 +1,68 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.core.CommandStore; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; + +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true") +final class IdempotencyCheckCommandHook implements CommandHookBefore { + + private final CommandStore store; + + @Override + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + + if (StringUtils.isNotEmpty(command.getIdempotencyKey())) { + var exists = store.existsByKey(command.getIdempotencyKey()); + + if (exists) { + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + + var isSameRequestClass = store.checkRequestInstanceByKey(command.getIdempotencyKey(), command.getPayload().getClass()); + + log.warn("Duplicate key detected: {} (same request class = {})", command.getIdempotencyKey(), isSameRequestClass); + + if (isSameRequestClass) { + var response = store.getResponseByKey(command.getIdempotencyKey()); + + ctx.setResponse(response); + } + + // TODO: else throw an exception? + } + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java new file mode 100644 index 00000000000..5981fd47c74 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java @@ -0,0 +1,52 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE; +import static org.apache.fineract.command.util.ServletHeaderUtil.getHeader; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; + +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE, havingValue = "true") +final class IdempotencyKeyHeaderCommandHook implements CommandHookBefore { + + private final IdempotencyCommandProperties properties; + + @Override + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + + if (StringUtils.isEmpty(command.getIdempotencyKey())) { + command.setIdempotencyKey(getHeader(properties.getKeyHeaderName(), true)); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java new file mode 100644 index 00000000000..6a514965317 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java @@ -0,0 +1,34 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.starter; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; + +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.context.annotation.ComponentScan; + +@AutoConfiguration +@EnableConfigurationProperties({ IdempotencyCommandProperties.class }) +@ComponentScan(COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_ENABLED, havingValue = "true") +public class IdempotencyCommandAutoConfiguration {} diff --git a/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports new file mode 100644 index 00000000000..57527f50053 --- /dev/null +++ b/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports @@ -0,0 +1 @@ +org.apache.fineract.command.idempotency.starter.IdempotencyCommandAutoConfiguration diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java new file mode 100644 index 00000000000..4f5d110ced7 --- /dev/null +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class JdbcCommandConstants { + + private JdbcCommandConstants() {} + + public static final String COMMAND_JDBC_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".jdbc"; + public static final String COMMAND_JDBC_PROPERTY_ENABLED = COMMAND_JDBC_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_JDBC_STORE_BASE_PACKAGE = "org.apache.fineract.command.jdbc.store"; +} diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java index d7e0e2ebace..8ad38a104ca 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.jdbc; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import lombok.AllArgsConstructor; @@ -32,7 +34,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.jdbc") +@ConfigurationProperties(prefix = COMMAND_JDBC_PROPERTIES_PREFIX) public final class JdbcCommandProperties implements Serializable { @Serial diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java index c7603d54940..813ed6a8247 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.jdbc.starter; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_PROPERTY_ENABLED; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_STORE_BASE_PACKAGE; + import java.util.List; import org.apache.fineract.command.jdbc.JdbcCommandProperties; import org.apache.fineract.command.jdbc.store.converter.JsonNodeReadingConverter; @@ -31,8 +34,8 @@ @AutoConfiguration @EnableConfigurationProperties(JdbcCommandProperties.class) -@ComponentScan("org.apache.fineract.command.jdbc.store") -@ConditionalOnProperty(value = "fineract.command.jdbc.enabled", havingValue = "true") +@ComponentScan(COMMAND_JDBC_STORE_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_JDBC_PROPERTY_ENABLED, havingValue = "true") public class JdbcCommandAutoConfiguration { @Bean diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java index c943b0578e6..ef880f13c2d 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java @@ -21,7 +21,6 @@ import static java.nio.charset.StandardCharsets.UTF_8; import static java.util.Objects.isNull; import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; -import static org.apache.fineract.command.core.CommandState.UNKNOWN; import io.github.resilience4j.retry.annotation.Retry; import java.io.IOException; @@ -33,12 +32,12 @@ import lombok.extern.slf4j.Slf4j; import org.apache.commons.io.FileUtils; import org.apache.fineract.command.core.Command; -import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandStore; import org.apache.fineract.command.jdbc.JdbcCommandProperties; import org.apache.fineract.command.jdbc.store.domain.CommandEntity; -import org.apache.fineract.command.jdbc.store.domain.CommandRepository; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.jdbc.store.mapping.JdbcCommandMapper; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.context.event.ApplicationStartedEvent; import org.springframework.context.event.EventListener; @@ -51,35 +50,30 @@ @ConditionalOnMissingBean(value = CommandStore.class, ignored = JdbcCommandStore.class) public class JdbcCommandStore implements CommandStore { - private final CommandMapper mapper; - private final CommandRepository repository; + private final JdbcCommandMapper mapper; + private final JdbcCommandRepository repository; private final ObjectMapper objectMapper; private final JdbcCommandProperties properties; @Override - @SuppressWarnings("unchecked") - public T getRequestById(Long id) { - return (T) repository.findById(id).map(CommandEntity::getRequest) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public Command getById(Long id) { + return repository.findById(id).map(mapper::map).orElse(null); } @Override - @SuppressWarnings("unchecked") - public T getResponseById(Long id) { - return (T) repository.findById(id).map(CommandEntity::getResponse) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public Command getByKey(String key) { + return repository.findOneByIdempotencyKey(key).map(mapper::map).orElse(null); } @Override - public org.apache.fineract.command.core.CommandState getStateById(Long id) { - return repository.findById(id).map(CommandEntity::getState).orElse(UNKNOWN); + public boolean existsByKey(String key) { + return repository.existsByIdempotencyKey(key); } @Override - @SuppressWarnings("unchecked") - public T getRequestByKey(String key) { - return (T) repository.findOneByIdempotencyKey(key).map(CommandEntity::getRequest) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public boolean checkRequestInstanceByKey(String key, Class clazz) { + return repository.findOneByIdempotencyKey(key).map(CommandEntity::getResponse) + .map(json -> clazz.getCanonicalName().equals(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asText())).orElse(false); } @Override @@ -89,15 +83,15 @@ public T getResponseByKey(String key) { .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); } - @Override - public CommandState getStateByKey(String key) { - return repository.findOneByIdempotencyKey(key).map(CommandEntity::getState).orElse(UNKNOWN); - } - @Override @Retry(name = "commandStore", fallbackMethod = "fallback") - public void store(Command command, Object response, CommandState state) { + public void store(CommandContext ctx) { final long startedAt = System.nanoTime(); + + final var command = ctx.getCommand(); + final var response = ctx.getResponse(); + final var state = ctx.getState(); + final var commandEntity = isNull(response) ? mapper.map(command) : mapper.map(command, response); if (state != null) { @@ -119,7 +113,10 @@ public void store(Command command, Object response, CommandState state) { } } - void fallback(Command command, Object response, CommandState state, Throwable t) throws Exception { + void fallback(CommandContext ctx, Throwable t) throws Exception { + final var command = ctx.getCommand(); + final var state = ctx.getState(); + log.warn("Command store fallback idempotencyKey={}, state={}, payloadType={}, deadLetterQueueEnabled={}", command.getIdempotencyKey(), state, payloadType(command), properties.getFileDeadLetterQueueEnabled(), t); if (Boolean.TRUE.equals(properties.getFileDeadLetterQueueEnabled())) { diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java similarity index 85% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java rename to fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java index 7e5e34ea9ad..dcec7c4816a 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java @@ -22,7 +22,9 @@ import org.springframework.data.repository.ListCrudRepository; import org.springframework.data.repository.query.QueryByExampleExecutor; -public interface CommandRepository extends ListCrudRepository, QueryByExampleExecutor { +public interface JdbcCommandRepository extends ListCrudRepository, QueryByExampleExecutor { Optional findOneByIdempotencyKey(String idempotencyKey); + + boolean existsByIdempotencyKey(String idempotencyKey); } diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java similarity index 97% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandMapper.java rename to fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java index b83867335ef..9a4fe19e585 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandMapper.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java @@ -27,8 +27,8 @@ import org.mapstruct.Mapper; import org.mapstruct.Mapping; -@Mapper(componentModel = SPRING, injectionStrategy = CONSTRUCTOR, uses = { CommandJsonMapper.class }) -public interface CommandMapper { +@Mapper(componentModel = SPRING, injectionStrategy = CONSTRUCTOR, uses = { JsonCommandMapper.class }) +public interface JdbcCommandMapper { @Mapping(source = "commandId", target = "id") @Mapping(source = "createdAt", target = "createdAt") diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandJsonMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java similarity index 98% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandJsonMapper.java rename to fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java index dfcd2103836..faaa5369de8 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandJsonMapper.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java @@ -31,7 +31,7 @@ @Slf4j @RequiredArgsConstructor @Component -public final class CommandJsonMapper { +public final class JsonCommandMapper { private final ObjectMapper mapper; diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml index ac42af8aafe..5579401453b 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml @@ -24,4 +24,6 @@ xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.1.xsd"> + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml new file mode 100644 index 00000000000..29376532cba --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml @@ -0,0 +1,43 @@ + + + + + + + idempotency_key IN ( + SELECT c1.idempotency_key + FROM m_command c1 + INNER JOIN m_command c2 + ON c1.idempotency_key = c2.idempotency_key + AND c1.id > c2.id + ) + + + + + + diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java similarity index 89% rename from fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java rename to fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java index df2b2e80285..d8440147e96 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java @@ -22,8 +22,8 @@ import java.time.Instant; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.jdbc.store.domain.CommandRepository; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.jdbc.store.mapping.JdbcCommandMapper; import org.apache.fineract.command.test.CommandBaseTest; import org.apache.fineract.command.test.sample.command.DummyCommand; import org.apache.fineract.command.test.sample.data.DummyRequest; @@ -36,13 +36,13 @@ @Slf4j @SpringBootTest @ContextConfiguration(classes = TestConfiguration.class) -class CommandRepositoryTest extends CommandBaseTest { +class JdbcCommandRepositoryTest extends CommandBaseTest { @Autowired - protected CommandRepository commandRepository; + protected JdbcCommandRepository commandRepository; @Autowired - protected CommandMapper commandMapper; + protected JdbcCommandMapper commandMapper; @Test void save() { diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java index 35f9c1db86f..d56cb188dfd 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java @@ -22,6 +22,15 @@ public final class CommandConstants { private CommandConstants() {} + public static final String COMMAND_PROPERTIES_PREFIX = "fineract.command"; + public static final String COMMAND_PROPERTY_ENABLED = COMMAND_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-servlet-headers-enabled"; + public static final String COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-timestamp-enabled"; + public static final String COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-username-enabled"; + public static final String COMMAND_BASE_PACKAGE = "org.apache.fineract.command"; + public static final String COMMAND_CORE_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".core"; + public static final String COMMAND_HOOK_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".hook"; + public static final String COMMAND_IMPLEMENTATION_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".implementation"; public static final String COMMAND_JSON_CLASS_ATTRIBUTE = "@class"; public static final String COMMAND_HTTP_HEADER_REQUEST_ID = "x-fineract-request-id"; public static final String COMMAND_HTTP_HEADER_TENANT_ID = "Fineract-Platform-TenantId"; diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java new file mode 100644 index 00000000000..c7a527dd68b --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java @@ -0,0 +1,53 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; + +import java.io.Serial; +import java.io.Serializable; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Data; +import lombok.NoArgsConstructor; +import lombok.experimental.FieldNameConstants; + +@Builder +@Data +@NoArgsConstructor +@AllArgsConstructor +@FieldNameConstants +public final class CommandContext implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + private Command command; + + private RES response; + + private Throwable error; + + @Builder.Default + private CommandState state = UNDER_PROCESSING; + + private boolean skipExecution; + + private boolean skipHooks; +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java index ce479ab7f66..d252ce06cba 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java @@ -21,5 +21,5 @@ @FunctionalInterface public interface CommandHookAfter { - void onAfter(Command command, RES response); + void onAfter(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java index 7f5af0c6dc9..22d1ad09f4f 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java @@ -19,7 +19,7 @@ package org.apache.fineract.command.core; @FunctionalInterface -public interface CommandHookBefore { +public interface CommandHookBefore { - void onBefore(Command command); + void onBefore(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java index 2730dd68729..9eb4c7a026c 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java @@ -19,7 +19,7 @@ package org.apache.fineract.command.core; @FunctionalInterface -public interface CommandHookError { +public interface CommandHookError { - void onError(Command command, Throwable error); + void onError(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java index ca9f2d5e54c..cf589ae69ff 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java @@ -18,11 +18,12 @@ */ package org.apache.fineract.command.core; +@SuppressWarnings("rawtypes") public interface CommandHookManager { - void before(Command command); + void before(CommandContext ctx); - void after(Command command, Object response); + void after(CommandContext ctx); - void error(Command command, Throwable error); + void error(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java index 6450cb58901..086cb6a3c1a 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.core; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import java.util.HashMap; @@ -34,7 +36,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command") +@ConfigurationProperties(prefix = COMMAND_PROPERTIES_PREFIX) public final class CommandProperties implements Serializable { @Serial @@ -47,5 +49,11 @@ public final class CommandProperties implements Serializable { private Map hooks = new HashMap<>(); @Builder.Default - private String idemPotencyKeyHeaderName = "Idempotency-Key"; + private Boolean hookServletHeadersEnabled = true; + + @Builder.Default + private Boolean hookTimestampEnabled = true; + + @Builder.Default + private Boolean hookUsernameEnabled = true; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java index a93135c9e8e..1922d1c6d38 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java @@ -20,17 +20,15 @@ public interface CommandStore { - T getRequestById(Long id); + Command getById(Long id); - T getResponseById(Long id); + Command getByKey(String key); - CommandState getStateById(Long id); + boolean existsByKey(String key); - T getRequestByKey(String key); + boolean checkRequestInstanceByKey(String key, Class clazz); T getResponseByKey(String key); - CommandState getStateByKey(String key); - - void store(Command command, Object response, CommandState state); + void store(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java index b2bbeb3906b..7f07ccd87ae 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java @@ -20,51 +20,31 @@ import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_HEADERS; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HTTP_HEADER_IP; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED; +import static org.apache.fineract.command.util.ServletHeaderUtil.getHeader; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; -import org.apache.fineract.command.core.CommandProperties; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; -import org.springframework.web.context.request.RequestContextHolder; -import org.springframework.web.context.request.ServletRequestAttributes; @Slf4j @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_HEADERS) -@ConditionalOnProperty(value = "fineract.command.hooks.servlet-header-pre", havingValue = "true") -final class ServletHeadersCommandHook implements CommandHookBefore { - - private final CommandProperties properties; +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED, havingValue = "true") +final class ServletHeadersCommandHook implements CommandHookBefore { @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (StringUtils.isEmpty(command.getIpAddress())) { command.setIpAddress(getHeader(COMMAND_HTTP_HEADER_IP, false)); } - if (StringUtils.isEmpty(command.getIdempotencyKey())) { - command.setIdempotencyKey(getHeader(properties.getIdemPotencyKeyHeaderName(), false)); - } - } - - private String getHeader(String name, boolean searchParameter) { - var attributes = RequestContextHolder.getRequestAttributes(); - - if (attributes instanceof ServletRequestAttributes servletAttributes) { - var value = servletAttributes.getRequest().getHeader(name.toLowerCase()); - - if (searchParameter && StringUtils.isEmpty(value)) { - value = servletAttributes.getRequest().getParameter(name.toLowerCase()); - } - - return value; - } - - return null; } } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java index 5ddbf41abc1..cf6c23f23d6 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java @@ -19,11 +19,12 @@ package org.apache.fineract.command.hook; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_TIMESTAMP; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -33,11 +34,13 @@ @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_TIMESTAMP) -@ConditionalOnProperty(value = "fineract.command.hooks.timestamp-pre", havingValue = "true") -final class TimestampCommandHook implements CommandHookBefore { +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED, havingValue = "true") +final class TimestampCommandHook implements CommandHookBefore { @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (command.getCreatedAt() == null) { command.setCreatedAt(Instant.now()); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java index d3d0d74a43b..cfa8984973d 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java @@ -19,11 +19,12 @@ package org.apache.fineract.command.hook; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_USERNAME; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -34,13 +35,15 @@ @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_USERNAME) -@ConditionalOnProperty(value = "fineract.command.hooks.username-pre", havingValue = "true") -final class UsernameCommandHook implements CommandHookBefore { +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED, havingValue = "true") +final class UsernameCommandHook implements CommandHookBefore { private static final String DEFAULT_USERNAME = "unknown"; @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (StringUtils.isEmpty(command.getInitiatedByUsername())) { command.setInitiatedByUsername(getUsername()); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java b/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java index 535af2dc8c8..18c279fe67f 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java @@ -21,7 +21,7 @@ import java.util.List; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookAfter; import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandHookError; @@ -41,17 +41,50 @@ public class DefaultCommandHookManager implements CommandHookManager { private final List errorHooks; @Override - public void before(Command command) { - beforeHooks.forEach(processor -> processor.onBefore(command)); + public void before(CommandContext ctx) { + for (var hookBefore : beforeHooks) { + hookBefore.onBefore(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining pre hooks after: {}", hookBefore.getClass().getCanonicalName()); + } + return; + } + } } @Override - public void after(Command command, Object response) { - afterHooks.forEach(processor -> processor.onAfter(command, response)); + public void after(CommandContext ctx) { + for (var hookAfter : afterHooks) { + hookAfter.onAfter(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining post hooks after: {}", hookAfter.getClass().getCanonicalName()); + } + return; + } + } } @Override - public void error(Command command, Throwable error) { - errorHooks.forEach(processor -> processor.onError(command, error)); + public void error(CommandContext ctx) { + for (var hookError : errorHooks) { + hookError.onError(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining error hooks after: {}", hookError.getClass().getCanonicalName()); + } + return; + } + } } } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java b/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java index 227210e3381..546b88ca1dc 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java @@ -19,11 +19,13 @@ package org.apache.fineract.command.implementation; import static java.util.Objects.requireNonNull; +import static org.apache.fineract.command.core.CommandState.PROCESSED; import java.util.function.Supplier; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.core.CommandHandlerManager; import org.apache.fineract.command.core.CommandHookManager; @@ -43,17 +45,28 @@ public class SynchronousCommandDispatcher implements CommandDispatcher { public Supplier dispatch(final Command command) { requireNonNull(command, "Command must not be null"); + final var ctx = CommandContext.builder().command(command).build(); + return () -> { try { - hookManager.before(command); + hookManager.before(ctx); + + if (ctx.isSkipExecution()) { + return ctx.getResponse(); + } RES response = handlerManager.handle(command); - hookManager.after(command, response); + ctx.setResponse(response); + ctx.setState(PROCESSED); - return response; + hookManager.after(ctx); + + return ctx.getResponse(); } catch (Exception e) { - hookManager.error(command, e); + ctx.setError(e); + + hookManager.error(ctx); throw e; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java b/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java index c5048b75c28..c83726eaa05 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java @@ -18,6 +18,10 @@ */ package org.apache.fineract.command.starter; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_CORE_BASE_PACKAGE; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_BASE_PACKAGE; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_IMPLEMENTATION_BASE_PACKAGE; + import org.apache.fineract.command.core.CommandProperties; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.ComponentScan; @@ -25,7 +29,7 @@ @Configuration @EnableConfigurationProperties(CommandProperties.class) -@ComponentScan("org.apache.fineract.command.core") -@ComponentScan("org.apache.fineract.command.hook") -@ComponentScan("org.apache.fineract.command.implementation") +@ComponentScan(COMMAND_CORE_BASE_PACKAGE) +@ComponentScan(COMMAND_HOOK_BASE_PACKAGE) +@ComponentScan(COMMAND_IMPLEMENTATION_BASE_PACKAGE) class CommandConfiguration {} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java new file mode 100644 index 00000000000..9ce7cd13ea2 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java @@ -0,0 +1,44 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.util; + +import org.apache.commons.lang3.StringUtils; +import org.springframework.web.context.request.RequestContextHolder; +import org.springframework.web.context.request.ServletRequestAttributes; + +public final class ServletHeaderUtil { + + private ServletHeaderUtil() {} + + public static String getHeader(String name, boolean searchParameter) { + var attributes = RequestContextHolder.getRequestAttributes(); + + if (attributes instanceof ServletRequestAttributes servletAttributes) { + var value = servletAttributes.getRequest().getHeader(name.toLowerCase()); + + if (searchParameter && StringUtils.isEmpty(value)) { + value = servletAttributes.getRequest().getParameter(name.toLowerCase()); + } + + return value; + } + + return null; + } +} diff --git a/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java index 6ec9ed28d5c..ab7b5005078 100644 --- a/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java +++ b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java @@ -36,13 +36,11 @@ import java.util.Map; import java.util.UUID; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.CommandProperties; import org.apache.fineract.command.test.sample.data.DummyRequest; import org.apache.fineract.command.test.sample.data.DummyResponse; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.server.LocalServerPort; import org.springframework.http.HttpEntity; @@ -69,9 +67,6 @@ class CommandSampleApiTest { private RestTemplate restTemplate; - @Autowired - private CommandProperties properties; - @BeforeEach public void setUp() { this.restTemplate = new RestTemplate(); @@ -106,14 +101,14 @@ void validation() { @Test void dummyApiSync() { final var content = "test-sync"; - final var idempotencyKey = UUID.randomUUID().toString(); + // final var idempotencyKey = UUID.randomUUID().toString(); restTemplate.setInterceptors(interceptors); - final var headers = new HttpHeaders(); - headers.add(properties.getIdemPotencyKeyHeaderName(), idempotencyKey); + // final var headers = new HttpHeaders(); + // headers.add(properties.getIdemPotencyKeyHeaderName(), idempotencyKey); - final var request = new HttpEntity<>(DummyRequest.builder().content(content).build(), headers); + final var request = new HttpEntity<>(DummyRequest.builder().content(content).build(), new HttpHeaders()); final var result = restTemplate.postForObject(baseUrl + "/sync", request, DummyResponse.class); diff --git a/fineract-command/src/test/resources/application-test.properties b/fineract-command/src/test/resources/application-test.properties index 6b548107d11..182badf97be 100644 --- a/fineract-command/src/test/resources/application-test.properties +++ b/fineract-command/src/test/resources/application-test.properties @@ -23,6 +23,6 @@ debug=true fineract.command.enabled=true -fineract.command.hooks.servlet-header-pre=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_PRE:true} -fineract.command.hooks.timestamp-pre=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_PRE:true} -fineract.command.hooks.username-pre=${FINERACT_COMMAND_PROCESSORS_USERNAME_PRE:true} +fineract.command.hook-servlet-headers-enabled=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADERS_ENABLED:true} +fineract.command.hook-timestamp-enabled=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_ENABLED:true} +fineract.command.hook-username-enabled=${FINERACT_COMMAND_PROCESSORS_USERNAME_ENABLED:true} diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index c2f162884f0..d172967a3c9 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -1,5 +1,7 @@ = Idempotency +IMPORTANT: The idempotency mechanics of the new command processing infrastructure still need to be documented. The implementation is done as a command hook. Detailed documentation will be provided soon. The only thing that new and legacy idempotency capabilities have in common is the name and configuration of the HTTP header name that contains the idempotency key. + Idempotency is the way to make sure your specific action is only executed once. For example, if you have a button that is supposed to send a repayment, you don’t want to repayment twice if the user clicks the button twice. Idempotency is a way to make sure that the action is only executed once. diff --git a/fineract-provider/dependencies.gradle b/fineract-provider/dependencies.gradle index 8712f19709c..4149e3d09f1 100644 --- a/fineract-provider/dependencies.gradle +++ b/fineract-provider/dependencies.gradle @@ -29,6 +29,7 @@ dependencies { implementation(project(path: ':fineract-command')) implementation(project(path: ':fineract-command-audit')) implementation(project(path: ':fineract-command-jdbc')) + implementation(project(path: ':fineract-command-idempotency')) implementation(project(path: ':fineract-validation')) implementation(project(path: ':fineract-accounting')) implementation(project(path: ':fineract-investor')) diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java b/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java index 520245966c2..10f774d35ea 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java @@ -21,7 +21,6 @@ import java.util.List; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; import org.apache.fineract.template.data.TemplateCreateRequest; import org.apache.fineract.template.data.TemplateCreateResponse; import org.apache.fineract.template.data.TemplateData; @@ -47,8 +46,6 @@ @ConditionalOnMissingBean(value = TemplateDomainService.class, ignored = TemplateDomainServiceImpl.class) public class TemplateDomainServiceImpl implements TemplateDomainService { - private final CommandMapper commandMapper; - private final TemplateRepository templateRepository; private final TemplateMapper templateMapper; private final TemplateMapperDataMapper templateMapperDataMapper; diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index 5367286a464..3fbbda00389 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -899,15 +899,14 @@ fineract.command.jdbc.enabled=${FINERACT_COMMAND_JDBC_ENABLED:true} fineract.command.jdbc.file-dead-letter-queue-enabled=${FINERACT_COMMAND_JDBC_FILE_DEAD_LETTER_QUEUE_ENABLED:false} fineract.command.jdbc.file-dead-letter-queue-path=${FINERACT_COMMAND_JDBC_FILE_DEAD_LETTER_QUEUE_PATH:/tmp/fineract/dlq} fineract.command.audit.enabled=${FINERACT_COMMAND_AUDIT_ENABLED:true} -fineract.command.hooks.audit-pre=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE:true} -fineract.command.hooks.audit-post=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST:true} -fineract.command.hooks.audit-error=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR:true} -fineract.command.hooks.servlet-header-pre=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_PRE:true} -fineract.command.hooks.timestamp-pre=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_PRE:true} -fineract.command.hooks.username-pre=${FINERACT_COMMAND_PROCESSORS_USERNAME_PRE:true} +fineract.command.audit.hook-pre-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE_ENABLED:true} +fineract.command.audit.hook-post-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED:true} +fineract.command.audit.hook-error-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR_ENABLED:true} +fineract.command.hook-servlet-headers-enabled=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_ENABLED:true} +fineract.command.hook-timestamp-enabled=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_ENABLED:true} +fineract.command.hook-username-enabled=${FINERACT_COMMAND_PROCESSORS_USERNAME_ENABLED:true} # TODO: move to separate module # this is duplicated on purpose to keep fineract-command independent; once all modules are migrated we clean up -fineract.command.idempotency-key-header-name=${FINERACT_IDEMPOTENCY_KEY_HEADER_NAME:Idempotency-Key} # command store @@ -936,5 +935,13 @@ resilience4j.retry.instances.tenantContextLookup.retryExceptions=${FINERACT_TENA # fineract.command.disruptor.ring-buffer-size=${FINERACT_COMMAND_RING_BUFFER_SIZE:1024} # fineract.command.disruptor.producer-type=${FINERACT_COMMAND_PRODUCER_TYPE:single} +# command idempotency + +fineract.command.idempotency.enabled=${FINERACT_COMMAND_IDEMPOTENCY_ENABLED:true} +# note: keep environment variable name for backwards compatibility +fineract.command.idempotency.key-header-name=${FINERACT_IDEMPOTENCY_KEY_HEADER_NAME:Idempotency-Key} +fineract.command.idempotency.hook-key-header-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_KEY_HEADER_PRE:true} +fineract.command.idempotency.hook-check-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_CHECK_PRE:true} + # Fineract Default Config values fineract.defaults.office-id=${FINERACT_CONFIG_DEFAULT_OFFICE_ID:1} diff --git a/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java b/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java index beae8b6aced..92c1020452e 100644 --- a/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java +++ b/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java @@ -22,7 +22,6 @@ import static org.mockito.Mockito.when; import java.util.List; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; import org.apache.fineract.template.data.TemplateData; import org.apache.fineract.template.data.TemplateMapperData; import org.apache.fineract.template.domain.Template; @@ -40,9 +39,6 @@ @ExtendWith(MockitoExtension.class) class TemplateDomainServiceImplTest { - @Mock - private CommandMapper commandMapper; - @Mock private TemplateRepository templateRepository; diff --git a/fineract-provider/src/test/resources/application-test.properties b/fineract-provider/src/test/resources/application-test.properties index 929985f8259..b9851c21e1d 100644 --- a/fineract-provider/src/test/resources/application-test.properties +++ b/fineract-provider/src/test/resources/application-test.properties @@ -362,9 +362,9 @@ fineract.command.jdbc.enabled=true fineract.command.jdbc.file-dead-letter-queue-enabled=false fineract.command.jdbc.file-dead-letter-queue-path=./build/fineract/dlq fineract.command.audit.enabled=true -fineract.command.hooks.audit-pre=true -fineract.command.hooks.audit-post=true -fineract.command.hooks.audit-error=true -fineract.command.hooks.servlet-header-pre=true -fineract.command.hooks.timestamp-pre=true -fineract.command.hooks.username-pre=true +fineract.command.audit.hook-pre-enabled=true +fineract.command.audit.hook-post-enabled=true +fineract.command.audit.hook-error-enabled=true +fineract.command.hook-servlet-headers-enabled=true +fineract.command.hook-timestamp-enabled=true +fineract.command.hook-username-enabled=true diff --git a/settings.gradle b/settings.gradle index 17e3ea136d6..24685d79748 100644 --- a/settings.gradle +++ b/settings.gradle @@ -65,6 +65,7 @@ include ':fineract-command-jdbc' include ':fineract-command-audit' include ':fineract-command-async' include ':fineract-command-disruptor' +include ':fineract-command-idempotency' include ':fineract-accounting' include ':fineract-provider' include ':fineract-branch' From b3f7d2563ee2730abc857b373bcef38a5af992d2 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Mon, 9 Nov 2026 19:07:28 +0000 Subject: [PATCH 02/11] FINERACT-2485: Adapt webhook command hooks to the context-based hook interface The hook interfaces now take a CommandContext rather than the command and its result as separate arguments. WebhookCommandHookAfter and WebhookCommandHookError landed on develop against the old signatures, so they are adapted here; the after hook still reads the response before registering the synchronization, so a webhook reports the result as it was when the command finished. --- .../hooks/command/WebhookCommandHookAfter.java | 9 +++++++-- .../hooks/command/WebhookCommandHookError.java | 10 ++++++---- .../command/WebhookCommandHookAfterTest.java | 16 +++++++++++----- .../command/WebhookCommandHookErrorTest.java | 18 ++++++++++++------ 4 files changed, 36 insertions(+), 17 deletions(-) diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java index 4cd4e71aa9d..31da6d756db 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java @@ -19,7 +19,7 @@ package org.apache.fineract.infrastructure.hooks.command; import lombok.RequiredArgsConstructor; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookAfter; import org.apache.fineract.command.core.HookableCommand; import org.springframework.stereotype.Component; @@ -38,11 +38,16 @@ final class WebhookCommandHookAfter implements CommandHookAfter private final WebhookCommandEventPublisher publisher; @Override - public void onAfter(Command command, Object response) { + public void onAfter(CommandContext ctx) { + var command = ctx.getCommand(); + if (!(command instanceof HookableCommand hookable)) { return; } + // read before registering, so that what is published is the response as it was when the command finished + var response = ctx.getResponse(); + // Inside an enclosing (e.g. batch) transaction, wait for the commit so that webhooks never fire for a command // that is rolled back by a later failure, as in the legacy command processing. if (TransactionSynchronizationManager.isSynchronizationActive()) { diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java index ba4d9b71dbb..bc5877bf670 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java @@ -19,7 +19,7 @@ package org.apache.fineract.infrastructure.hooks.command; import lombok.RequiredArgsConstructor; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookError; import org.apache.fineract.command.core.HookableCommand; import org.springframework.stereotype.Component; @@ -31,12 +31,14 @@ */ @RequiredArgsConstructor @Component -final class WebhookCommandHookError implements CommandHookError { +final class WebhookCommandHookError implements CommandHookError { private final WebhookCommandEventPublisher publisher; @Override - public void onError(Command command, Throwable error) { + public void onError(CommandContext ctx) { + var command = ctx.getCommand(); + if (!(command instanceof HookableCommand hookable)) { return; } @@ -44,6 +46,6 @@ public void onError(Command command, Throwable error) { // Publish right away, as in the legacy command processing: when the handler fails, its work is rolled back, so // there is no commit to wait for. A hook can also fail after the handler has committed, e.g. when the audit // hook can't store the command. The event then reports the error the API returns, for a change that was saved. - publisher.publishError(hookable, command.getPayload(), error); + publisher.publishError(hookable, command.getPayload(), ctx.getError()); } } diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java index 1415941da4a..55fe6aa322a 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java @@ -37,6 +37,7 @@ import java.util.HashMap; import java.util.Map; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.HookableCommand; import org.apache.fineract.infrastructure.businessdate.domain.BusinessDateType; import org.apache.fineract.infrastructure.core.exception.ErrorHandler; @@ -88,7 +89,7 @@ void tearDown() { void shouldPublishHookEventForHookableCommand() { final TestResponse response = new TestResponse(7L); - underTest.onAfter(hookableCommand(), response); + underTest.onAfter(afterContext(hookableCommand(), response)); final HookEvent event = publishedEvent(); final HookEventSource source = (HookEventSource) event.getSource(); @@ -113,7 +114,7 @@ void shouldPublishHookEventForHookableCommand() { @Test void shouldExposeOfficeAndClientAtTopLevelOfPayload() { - underTest.onAfter(hookableCommand(), new TestClientResponse(7L, 2L, 3L)); + underTest.onAfter(afterContext(hookableCommand(), new TestClientResponse(7L, 2L, 3L))); final JsonNode payload = mapper.readTree(publishedEvent().getPayload()); assertEquals(2L, payload.get("officeId").asLong()); @@ -128,7 +129,7 @@ void shouldIgnoreCommandThatIsNotHookable() { final Command command = new Command<>(); command.setPayload(new TestRequest("contract.pdf", null)); - underTest.onAfter(command, new TestResponse(7L)); + underTest.onAfter(afterContext(command, new TestResponse(7L))); verifyNoInteractions(eventPublisher); } @@ -137,7 +138,7 @@ void shouldIgnoreCommandThatIsNotHookable() { void shouldDeferPublicationUntilEnclosingTransactionCommits() { TransactionSynchronizationManager.initSynchronization(); - underTest.onAfter(hookableCommand(), new TestResponse(7L)); + underTest.onAfter(afterContext(hookableCommand(), new TestResponse(7L))); verifyNoInteractions(eventPublisher); @@ -150,7 +151,7 @@ void shouldDeferPublicationUntilEnclosingTransactionCommits() { void shouldNotFailCommandWhenPublishingFails() { doThrow(new IllegalStateException("listener failed")).when(eventPublisher).publishEvent(any(HookEvent.class)); - assertDoesNotThrow(() -> underTest.onAfter(hookableCommand(), new TestResponse(7L))); + assertDoesNotThrow(() -> underTest.onAfter(afterContext(hookableCommand(), new TestResponse(7L)))); } private HookEvent publishedEvent() { @@ -186,4 +187,9 @@ private record TestResponse(Long resourceId) { private record TestClientResponse(Long resourceId, Long officeId, Long clientId) { } + + /** The hook takes the context now, so the command and its result are handed over together. */ + private static CommandContext afterContext(Command command, Object response) { + return CommandContext.builder().command(command).response(response).build(); + } } diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java index af68e2a6f08..ab4a4038e8e 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java @@ -38,6 +38,7 @@ import java.util.Map; import org.apache.fineract.batch.exception.ErrorInfo; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.HookableCommand; import org.apache.fineract.infrastructure.businessdate.domain.BusinessDateType; import org.apache.fineract.infrastructure.core.exception.ErrorHandler; @@ -94,7 +95,7 @@ void shouldPublishExceptionEventForHookableCommand() { final IllegalStateException error = new IllegalStateException("not found"); when(errorHandler.handle(error)).thenReturn(new ErrorInfo(404, 4001, NOT_FOUND_BODY, null)); - underTest.onError(hookableCommand(), error); + underTest.onError(errorContext(hookableCommand(), error)); final HookEvent event = publishedEvent(); final HookEventSource source = (HookEventSource) event.getSource(); @@ -124,7 +125,7 @@ void shouldPublishExceptionEventForHookableCommand() { void shouldSendErrorMessageThatIsNotJsonAsIs() { when(errorHandler.handle(any())).thenReturn(new ErrorInfo(500, null, "Unexpected failure", null)); - underTest.onError(hookableCommand(), new IllegalStateException("boom")); + underTest.onError(errorContext(hookableCommand(), new IllegalStateException("boom"))); final JsonNode response = mapper.readTree(publishedEvent().getPayload()).get("response"); assertEquals("Unexpected failure", response.get("errorMessage").asString()); @@ -137,7 +138,7 @@ void shouldPublishImmediatelyInsideEnclosingTransaction() { TransactionSynchronizationManager.initSynchronization(); when(errorHandler.handle(any())).thenReturn(new ErrorInfo(404, 4001, NOT_FOUND_BODY, null)); - underTest.onError(hookableCommand(), new IllegalStateException("not found")); + underTest.onError(errorContext(hookableCommand(), new IllegalStateException("not found"))); assertEquals("Exception", mapper.readTree(publishedEvent().getPayload()).get("status").asString()); assertTrue(TransactionSynchronizationManager.getSynchronizations().isEmpty()); @@ -148,7 +149,7 @@ void shouldIgnoreCommandThatIsNotHookable() { final Command command = new Command<>(); command.setPayload(new TestRequest("contract.pdf", null)); - underTest.onError(command, new IllegalStateException("not found")); + underTest.onError(errorContext(command, new IllegalStateException("not found"))); verifyNoInteractions(eventPublisher, errorHandler); } @@ -158,14 +159,14 @@ void shouldNotMaskCommandErrorWhenPublishingFails() { when(errorHandler.handle(any())).thenReturn(new ErrorInfo(404, 4001, NOT_FOUND_BODY, null)); doThrow(new IllegalStateException("listener failed")).when(eventPublisher).publishEvent(any(HookEvent.class)); - assertDoesNotThrow(() -> underTest.onError(hookableCommand(), new IllegalStateException("not found"))); + assertDoesNotThrow(() -> underTest.onError(errorContext(hookableCommand(), new IllegalStateException("not found")))); } @Test void shouldNotMaskCommandErrorWhenMappingTheErrorFails() { when(errorHandler.handle(any())).thenThrow(new IllegalStateException("no mapper")); - assertDoesNotThrow(() -> underTest.onError(hookableCommand(), new IllegalStateException("not found"))); + assertDoesNotThrow(() -> underTest.onError(errorContext(hookableCommand(), new IllegalStateException("not found")))); verifyNoInteractions(eventPublisher); } @@ -196,4 +197,9 @@ public String hookActionName() { private record TestRequest(String name, @JsonIgnore InputStream stream) { } + + /** The hook takes the context now, so the command and the failure are handed over together. */ + private static CommandContext errorContext(Command command, Throwable error) { + return CommandContext.builder().command(command).error(error).build(); + } } From 9b5a43be8c91a01837745a0261832bf641866d81 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Mon, 9 Nov 2026 19:07:29 +0000 Subject: [PATCH 03/11] FINERACT-2485: Make the Jackson 3 command store agree with the Jersey wire format Commands are persisted on Jackson 3 while Jersey can only run on Jackson 2, so the two mappers have to produce the same bytes. Three Jackson 3 defaults differ and are pinned by tests: WRITE_DATES_AS_TIMESTAMPS and WRITE_DURATIONS_AS_TIMESTAMPS are off, and java.time.Month is written as a number with no flag to restore the name - a Jackson 2 client reads that back as an ordinal and gets the wrong month. It also reapplies credential masking. @JsonSerialize(using = MaskedValueSerializer.class) is a Jackson 2 annotation and invisible to Jackson 3, so without this external-service credentials would reach the command table in the clear. --- .../jackson3/Jackson3ObjectMapperConfig.java | 67 ++++ .../jackson3/Jackson3WebFormatModule.java | 308 ++++++++++++++++++ .../CommandReplayRehydrationTest.java | 146 +++++++++ .../core/jackson3/CommandResponseSample.java | 76 +++++ .../Jackson3ObjectMapperWiringTest.java | 64 ++++ .../JacksonWireFormatEquivalenceTest.java | 232 +++++++++++++ ...JacksonWireFormatCharacterizationTest.java | 209 ++++++++++++ 7 files changed, 1102 insertions(+) create mode 100644 fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java create mode 100644 fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3WebFormatModule.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandResponseSample.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperWiringTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/JacksonWireFormatEquivalenceTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jersey/JacksonWireFormatCharacterizationTest.java diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java new file mode 100644 index 00000000000..881746648a3 --- /dev/null +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java @@ -0,0 +1,67 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import com.fasterxml.jackson.annotation.JsonInclude; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import tools.jackson.databind.DeserializationFeature; +import tools.jackson.databind.MapperFeature; +import tools.jackson.databind.cfg.DateTimeFeature; +import tools.jackson.databind.json.JsonMapper; + +/** + * The application's Jackson 3 mapper, configured to agree with the Jackson 2 one that serves the REST API. + * + *

+ * Defining it replaces the mapper Spring Boot would otherwise auto-configure, which is a stock Jackson 3 mapper with + * none of this. Everything injecting a Jackson 3 {@code ObjectMapper} gets this one; the command store, which persists + * command requests and responses and replays a stored response when a request repeats under the same idempotency key, + * is the consumer that makes the agreement matter. + * + *

+ * The feature settings are the ones where Jackson 3 changed a default out from under Jackson 2. Each was found by + * comparing the two mappers' output rather than by reading release notes, and each is held in place by + * {@code JacksonWireFormatEquivalenceTest}. {@code com.fasterxml.jackson.annotation} is shared by both versions, so + * {@link JsonInclude} below is deliberately the Jackson 2 import. + * + *

+ * The declared return type has to stay {@link JsonMapper}, not {@code ObjectMapper}. Spring Boot's own Jackson 3 mapper + * is {@code @Primary} and backs off only on finding a bean declared as a {@code JsonMapper}; declare this one as an + * {@code ObjectMapper} and Boot builds its stock mapper anyway, wins on {@code @Primary}, and everything here is + * silently never used. {@code Jackson3ObjectMapperWiringTest} is what notices. + */ +@Configuration +public class Jackson3ObjectMapperConfig { + + @Bean + public JsonMapper jackson3ObjectMapper() { + return JsonMapper.builder() // + .addModule(new Jackson3WebFormatModule()) // + .changeDefaultPropertyInclusion(inclusion -> inclusion.withValueInclusion(JsonInclude.Include.NON_NULL)) // + .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // + .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS) // + // Jackson 3 turned both of these off. Any java.time value that no serializer above covers would + // otherwise change shape: a LocalDate inside a collection from [y,m,d] to a string, a Duration from a + // number of seconds to an ISO-8601 period. + .enable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS) // + .enable(DateTimeFeature.WRITE_DURATIONS_AS_TIMESTAMPS) // + .build(); + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3WebFormatModule.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3WebFormatModule.java new file mode 100644 index 00000000000..40e834826cf --- /dev/null +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3WebFormatModule.java @@ -0,0 +1,308 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import java.time.Instant; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.LocalTime; +import java.time.Month; +import java.time.OffsetDateTime; +import java.time.format.DateTimeFormatter; +import java.time.temporal.TemporalAccessor; +import java.util.Date; +import java.util.List; +import java.util.Locale; +import java.util.function.BiFunction; +import org.apache.fineract.infrastructure.core.domain.ExternalId; +import org.apache.fineract.infrastructure.core.jersey.serializer.MaskedValueSerializer; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JsonLocalDateArrayFormat; +import org.apache.fineract.infrastructure.core.service.StringUtil; +import tools.jackson.core.JsonGenerator; +import tools.jackson.core.JsonParser; +import tools.jackson.core.JsonToken; +import tools.jackson.databind.BeanDescription; +import tools.jackson.databind.DeserializationContext; +import tools.jackson.databind.SerializationConfig; +import tools.jackson.databind.SerializationContext; +import tools.jackson.databind.ValueDeserializer; +import tools.jackson.databind.ValueSerializer; +import tools.jackson.databind.module.SimpleModule; +import tools.jackson.databind.ser.BeanPropertyWriter; +import tools.jackson.databind.ser.ValueSerializerModifier; + +/** + * Teaches a Jackson 3 mapper to read and write exactly what the Jackson 2 mapper behind Jersey does. + * + *

+ * Commands are persisted by {@code fineract-command-jdbc}, which runs on Jackson 3, while responses reach the client + * through Jersey, which can only run on Jackson 2. A command's stored response is replayed when the same request + * arrives again under the same idempotency key, so the two have to agree: whatever Jackson 3 writes into the command + * table has to come back out as an object that Jackson 2 then renders byte for byte like the original response. + * + *

+ * This mirrors the converters in {@code JerseyJacksonConverterConfig} rather than sharing them, because that converter + * interface is typed against Jackson 2's {@code JsonParser} and {@code JsonGenerator}. The formats are the same + * {@link DateTimeFormatter} constants, and {@code JacksonWireFormatEquivalenceTest} fails if the two ever drift apart. + */ +public class Jackson3WebFormatModule extends SimpleModule { + + public Jackson3WebFormatModule() { + addFormatted(LocalDateTime.class, DateTimeFormatter.ISO_LOCAL_DATE_TIME, LocalDateTime::parse); + addFormatted(LocalTime.class, DateTimeFormatter.ISO_LOCAL_TIME, LocalTime::parse); + addFormatted(OffsetDateTime.class, DateTimeFormatter.ISO_OFFSET_DATE_TIME, OffsetDateTime::parse); + + addSerializer(Date.class, new DateSerializer()); + addDeserializer(Date.class, new DateDeserializer()); + addSerializer(ExternalId.class, new ExternalIdSerializer()); + addDeserializer(ExternalId.class, new ExternalIdDeserializer()); + + // Jackson 2 has no Month handler, so it falls through to ordinary enum handling and writes "OCTOBER". Jackson 3 + // added one that always writes a number, one-based by default. That is worse than a reformatting: a client + // reading 10 back through Jackson 2 resolves it as an ordinal and gets NOVEMBER, silently. No feature flag + // restores the name. + addSerializer(Month.class, new MonthNameSerializer()); + addDeserializer(Month.class, new MonthNameDeserializer()); + + setSerializerModifier(new LocalDateAndMaskedPropertyModifier()); + } + + private void addFormatted(Class type, DateTimeFormatter formatter, + BiFunction parser) { + addSerializer(type, new FormattedSerializer<>(type, formatter)); + addDeserializer(type, new FormattedDeserializer<>(type, formatter, parser)); + } + + private static final class FormattedSerializer extends ValueSerializer { + + private final Class type; + private final DateTimeFormatter formatter; + + private FormattedSerializer(Class type, DateTimeFormatter formatter) { + this.type = type; + this.formatter = formatter; + } + + @Override + public void serialize(T value, JsonGenerator gen, SerializationContext context) { + gen.writeString(formatter.format(value)); + } + + @Override + public Class handledType() { + return type; + } + } + + private static final class FormattedDeserializer extends ValueDeserializer { + + private final Class type; + private final DateTimeFormatter formatter; + private final BiFunction parser; + + private FormattedDeserializer(Class type, DateTimeFormatter formatter, BiFunction parser) { + this.type = type; + this.formatter = formatter; + this.parser = parser; + } + + @Override + public T deserialize(JsonParser jsonParser, DeserializationContext context) { + // The Jackson 2 converters read a string and yield null for anything else, rather than failing. + return jsonParser.hasToken(JsonToken.VALUE_STRING) ? parser.apply(jsonParser.getString(), formatter) : null; + } + + @Override + public Class handledType() { + return type; + } + } + + private static final class DateSerializer extends ValueSerializer { + + @Override + public void serialize(Date value, JsonGenerator gen, SerializationContext context) { + gen.writeString(DateTimeFormatter.ISO_INSTANT.format(value.toInstant())); + } + + @Override + public Class handledType() { + return Date.class; + } + } + + private static final class DateDeserializer extends ValueDeserializer { + + @Override + public Date deserialize(JsonParser parser, DeserializationContext context) { + return parser.hasToken(JsonToken.VALUE_STRING) + ? Date.from(Instant.from(DateTimeFormatter.ISO_INSTANT.parse(parser.getString()))) + : null; + } + + @Override + public Class handledType() { + return Date.class; + } + } + + private static final class ExternalIdSerializer extends ValueSerializer { + + @Override + public void serialize(ExternalId value, JsonGenerator gen, SerializationContext context) { + if (value != null && !value.isEmpty()) { + gen.writeString(value.getValue()); + } else { + gen.writeNull(); + } + } + + @Override + public Class handledType() { + return ExternalId.class; + } + } + + private static final class ExternalIdDeserializer extends ValueDeserializer { + + @Override + public ExternalId deserialize(JsonParser parser, DeserializationContext context) { + return parser.hasToken(JsonToken.VALUE_STRING) ? new ExternalId(parser.getString()) : ExternalId.empty(); + } + + @Override + public Class handledType() { + return ExternalId.class; + } + } + + private static final class MonthNameSerializer extends ValueSerializer { + + @Override + public void serialize(Month value, JsonGenerator gen, SerializationContext context) { + gen.writeString(value.name()); + } + + @Override + public Class handledType() { + return Month.class; + } + } + + private static final class MonthNameDeserializer extends ValueDeserializer { + + @Override + public Month deserialize(JsonParser parser, DeserializationContext context) { + if (parser.currentToken() == JsonToken.VALUE_NUMBER_INT) { + // Jackson 2 reads a number as the enum's ordinal, so a zero-based index, and so does this. + return Month.values()[parser.getIntValue()]; + } + return Month.valueOf(parser.getString().toUpperCase(Locale.ROOT)); + } + + @Override + public Class handledType() { + return Month.class; + } + } + + /** + * The Jackson 3 counterpart of {@code JacksonLocalDateBeanSerializerModifier}, which also carries the masking that + * Jackson 3 would otherwise drop. + * + *

+ * Both jobs belong here rather than in the module's type registrations. Registering a {@link LocalDate} serializer + * outright would also catch the ones inside collections, and Jackson 2 does not: a {@code LocalDate} property is + * written as a string while a {@code List} is written as {@code [year, month, day]} arrays. Clients + * depend on both shapes as they are. + * + *

+ * Masking has to be reapplied because {@code @JsonSerialize(using = MaskedValueSerializer.class)} is a Jackson + * 2 annotation, which Jackson 3 neither sees nor could use the serializer it names. Left alone, a command + * carrying external-service credentials would write them to the command table in the clear. + */ + private static final class LocalDateAndMaskedPropertyModifier extends ValueSerializerModifier { + + private final ValueSerializer localDateAsString = cast( + new FormattedSerializer<>(LocalDate.class, DateTimeFormatter.ISO_LOCAL_DATE)); + private final ValueSerializer localDateAsArray = cast(new LocalDateArraySerializer()); + private final ValueSerializer masked = cast(new MaskedSerializer()); + + @SuppressWarnings("unchecked") + private static ValueSerializer cast(ValueSerializer serializer) { + return (ValueSerializer) serializer; + } + + @Override + public List changeProperties(SerializationConfig config, BeanDescription.Supplier beanDesc, + List beanProperties) { + boolean legacyArrayFormat = beanDesc.getBeanClass().isAnnotationPresent(JsonLocalDateArrayFormat.class); + + for (BeanPropertyWriter writer : beanProperties) { + if (LocalDate.class.equals(writer.getType().getRawClass())) { + writer.assignSerializer(legacyArrayFormat ? localDateAsArray : localDateAsString); + } else if (isMasked(writer)) { + writer.assignSerializer(masked); + } + } + + return beanProperties; + } + + private static boolean isMasked(BeanPropertyWriter writer) { + var annotation = writer.getAnnotation(com.fasterxml.jackson.databind.annotation.JsonSerialize.class); + + return annotation != null && MaskedValueSerializer.class.equals(annotation.using()); + } + } + + private static final class LocalDateArraySerializer extends ValueSerializer { + + @Override + public void serialize(LocalDate value, JsonGenerator gen, SerializationContext context) { + if (value == null) { + gen.writeNull(); + return; + } + gen.writeStartArray(); + gen.writeNumber(value.getYear()); + gen.writeNumber(value.getMonthValue()); + gen.writeNumber(value.getDayOfMonth()); + gen.writeEndArray(); + } + + @Override + public Class handledType() { + return LocalDate.class; + } + } + + private static final class MaskedSerializer extends ValueSerializer { + + @Override + public void serialize(String value, JsonGenerator gen, SerializationContext context) { + gen.writeString(value == null || value.isBlank() ? value : StringUtil.maskValue(value)); + } + + @Override + public Class handledType() { + return String.class; + } + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java new file mode 100644 index 00000000000..d6f5d49206c --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java @@ -0,0 +1,146 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonDeserializer; +import com.fasterxml.jackson.databind.JsonSerializer; +import com.fasterxml.jackson.databind.MapperFeature; +import java.util.ArrayList; +import java.util.List; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; +import org.apache.fineract.infrastructure.core.jersey.converter.DateJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.ExternalIdJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.JsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.OffsetDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonDeserializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonSerializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JacksonLocalDateArrayModule; +import org.junit.jupiter.api.Test; +import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder; +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.ObjectMapper; + +/** + * Walks a command result through the replay path exactly as production does, and checks the client cannot tell. + * + *

+ * A command's result is written to the command table as an object by {@link JsonCommandMapper}, on Jackson 3. A repeat + * of the request reads that row back into an object and hands it to the web layer, which renders it with the same + * Jackson 2 mapper that rendered the first answer. Nothing re-renders stored text, so the two answers match because + * they are the same object through the same serializer — not because two mappers were talked into agreeing. + * + *

+ * What that leaves to check is the round trip in the middle: the stored object has to come back carrying every value it + * went in with. A decimal that loses its scale, a date that loses its precision or a credential that re-masks + * differently would all survive storage and still change the answer. + */ +class CommandReplayRehydrationTest { + + /** What Jersey renders responses with, first time and on replay alike. */ + private final com.fasterxml.jackson.databind.ObjectMapper jersey = jerseyObjectMapper(); + + private final ObjectMapper commandStoreMapper = new Jackson3ObjectMapperConfig().jackson3ObjectMapper(); + + private final JsonCommandMapper commandJsonMapper = new JsonCommandMapper(commandStoreMapper); + + private static com.fasterxml.jackson.databind.ObjectMapper jerseyObjectMapper() { + List> converters = List.of(new LocalDateTimeJsonConverter(), new OffsetDateTimeJsonConverter(), + new LocalTimeJsonConverter(), new DateJsonConverter(), new ExternalIdJsonConverter()); + + List> serializers = new ArrayList<>(converters.stream().map(JacksonSerializerAdapter::new).toList()); + List> deserializers = new ArrayList<>(converters.stream().map(JacksonDeserializerAdapter::new).toList()); + + com.fasterxml.jackson.databind.ObjectMapper objectMapper = new Jackson2ObjectMapperBuilder() // + .serializers(serializers.toArray(new JsonSerializer[0])) // + .serializationInclusion(JsonInclude.Include.NON_NULL) // + .deserializers(deserializers.toArray(new JsonDeserializer[0])) // + .featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // + .featuresToEnable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS) // + .build(); + + objectMapper.registerModule(new JacksonLocalDateArrayModule()); + + return objectMapper; + } + + @Test + void aReplayedAnswerIsByteForByteTheOriginalAnswer() throws Exception { + CommandResponseSample result = CommandResponseSample.populated(); + + String originalAnswer = jersey.writeValueAsString(result); + + JsonNode stored = commandJsonMapper.map(result); + CommandResponseSample rehydrated = commandJsonMapper.map(stored); + + assertNotNull(rehydrated, "The stored result must rehydrate; a null here means the type attribute did not resolve."); + assertEquals(originalAnswer, jersey.writeValueAsString(rehydrated), + "A repeat of the request must be answered with the bytes the first one was answered with."); + } + + @Test + void everyValueSurvivesTheRoundTrip() { + CommandResponseSample result = CommandResponseSample.populated(); + + CommandResponseSample rehydrated = commandJsonMapper.map(commandJsonMapper.map(result)); + + assertEquals(result.getAmount(), rehydrated.getAmount(), "A decimal must come back with its scale intact."); + assertEquals(result.getPrecise(), rehydrated.getPrecise(), "A high-precision decimal must not round."); + assertEquals(result.getOffsetDateTime(), rehydrated.getOffsetDateTime(), "Nanosecond precision must survive."); + assertEquals(result.getLocalDateTime(), rehydrated.getLocalDateTime()); + assertEquals(result.getLocalTime(), rehydrated.getLocalTime()); + assertEquals(result.getLocalDate(), rehydrated.getLocalDate()); + assertEquals(result.getDate(), rehydrated.getDate()); + assertEquals(result.getExternalId(), rehydrated.getExternalId()); + assertEquals(result.getResourceId(), rehydrated.getResourceId()); + assertEquals(result.getStatus(), rehydrated.getStatus()); + assertEquals(result.getDates(), rehydrated.getDates()); + } + + @Test + void theStoredRowCarriesItsTypeAndTheReplayDoesNot() throws Exception { + CommandResponseSample result = CommandResponseSample.populated(); + + JsonNode stored = commandJsonMapper.map(result); + + assertTrue(stored.has(COMMAND_JSON_CLASS_ATTRIBUTE), "The store records the result's type so it can be read back."); + assertFalse(jersey.writeValueAsString(commandJsonMapper.map(stored)).contains(COMMAND_JSON_CLASS_ATTRIBUTE), + "That type attribute is the store's bookkeeping and was never part of an answer, so a replay must not carry it."); + } + + @Test + void aCredentialIsStoredMaskedAndStillReplaysUnchanged() throws Exception { + CommandResponseSample result = CommandResponseSample.populated(); + + JsonNode stored = commandJsonMapper.map(result); + + assertFalse(stored.toString().contains("secret-value"), "Credentials must not reach the command table in the clear."); + assertEquals(jersey.writeValueAsString(result), jersey.writeValueAsString(commandJsonMapper.map(stored)), + "The stored copy is already masked, so the replay masks it a second time. That has to be a no-op."); + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandResponseSample.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandResponseSample.java new file mode 100644 index 00000000000..a5ad0d34efb --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandResponseSample.java @@ -0,0 +1,76 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import com.fasterxml.jackson.databind.annotation.JsonSerialize; +import java.math.BigDecimal; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.LocalTime; +import java.time.OffsetDateTime; +import java.util.Date; +import java.util.List; +import lombok.AllArgsConstructor; +import lombok.Data; +import lombok.NoArgsConstructor; +import org.apache.fineract.infrastructure.core.domain.ExternalId; +import org.apache.fineract.infrastructure.core.jersey.serializer.MaskedValueSerializer; + +/** + * Stands in for a command's result on the replay path. + * + *

+ * Deliberately a top-level class rather than a nested one, because {@code JsonCommandMapper} records the result's type + * with {@code getCanonicalName()} and reads it back with {@code Class.forName}. Those two agree for a top-level class + * and disagree for a nested one, whose canonical name uses a dot where the binary name uses a dollar — so a nested + * stand-in would exercise a path real command results never take. + */ +@Data +@NoArgsConstructor +@AllArgsConstructor +public class CommandResponseSample { + + private String text; + private Long resourceId; + private Integer count; + private BigDecimal amount; + private BigDecimal precise; + private Status status; + private LocalDate localDate; + private LocalDateTime localDateTime; + private OffsetDateTime offsetDateTime; + private LocalTime localTime; + private Date date; + private ExternalId externalId; + @JsonSerialize(using = MaskedValueSerializer.class) + private String secret; + private List dates; + + public static CommandResponseSample populated() { + return new CommandResponseSample("hello", Long.MAX_VALUE, 7, new BigDecimal("1.50"), + new BigDecimal("12345678901234567890.12345678901"), Status.ACTIVE, LocalDate.of(2026, 10, 5), + LocalDateTime.parse("2026-10-05T11:22:33.123456789"), OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z"), + LocalTime.parse("11:22:33.123456789"), Date.from(java.time.Instant.parse("2026-10-05T11:22:33Z")), new ExternalId("ext-1"), + "secret-value", List.of(LocalDate.of(2026, 1, 2), LocalDate.of(2026, 1, 3))); + } + + public enum Status { + ACTIVE, CLOSED + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperWiringTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperWiringTest.java new file mode 100644 index 00000000000..a03e9b0be59 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperWiringTest.java @@ -0,0 +1,64 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.apache.fineract.infrastructure.core.jersey.JacksonWireFormatCharacterizationTest; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.jackson.autoconfigure.JacksonAutoConfiguration; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import tools.jackson.databind.ObjectMapper; + +/** + * Checks that the mapper {@link Jackson3ObjectMapperConfig} defines is the one injected, not merely the one defined. + * + *

+ * Spring Boot auto-configures its own Jackson 3 mapper, annotated {@code @Primary}, and backs off only on finding a + * bean declared as a {@code JsonMapper}. Get that detail wrong and the context still starts, every mapper-level test + * still passes, and the command store quietly writes through Boot's stock mapper instead — unmasked credentials and + * all. Nothing else in the suite can see that, because everything else builds its mapper by calling the configuration + * class directly rather than by asking the container for one. + */ +class Jackson3ObjectMapperWiringTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(JacksonAutoConfiguration.class)) + .withUserConfiguration(Jackson3ObjectMapperConfig.class); + + @Test + void theConfiguredMapperIsTheOneInjected() { + contextRunner.run(context -> { + ObjectMapper injected = context.getBean(ObjectMapper.class); + + assertThat(injected.writeValueAsString(JacksonWireFormatCharacterizationTest.populated())) + .as("The Jackson 3 mapper handed to the command store must be the configured one, " + + "which masks credentials and writes a LocalDate property as an ISO string") + .doesNotContain("secret-value") // + .contains("\"localDate\":\"2026-10-05\""); + }); + } + + @Test + void bootDoesNotAlsoContributeAMapperOfItsOwn() { + contextRunner.run(context -> assertThat(context.getBeanNamesForType(ObjectMapper.class)) + .as("Two Jackson 3 mappers means the @Primary one wins, and it is not ours").containsExactly("jackson3ObjectMapper")); + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/JacksonWireFormatEquivalenceTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/JacksonWireFormatEquivalenceTest.java new file mode 100644 index 00000000000..d1d220fd8d1 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/JacksonWireFormatEquivalenceTest.java @@ -0,0 +1,232 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonDeserializer; +import com.fasterxml.jackson.databind.JsonSerializer; +import com.fasterxml.jackson.databind.MapperFeature; +import java.math.BigDecimal; +import java.math.BigInteger; +import java.time.DayOfWeek; +import java.time.Duration; +import java.time.Instant; +import java.time.LocalDate; +import java.time.Month; +import java.time.MonthDay; +import java.time.Period; +import java.time.Year; +import java.time.YearMonth; +import java.time.ZonedDateTime; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.UUID; +import lombok.AllArgsConstructor; +import lombok.Data; +import lombok.NoArgsConstructor; +import org.apache.fineract.infrastructure.core.jersey.JacksonWireFormatCharacterizationTest; +import org.apache.fineract.infrastructure.core.jersey.JacksonWireFormatCharacterizationTest.Everything; +import org.apache.fineract.infrastructure.core.jersey.JacksonWireFormatCharacterizationTest.Legacy; +import org.apache.fineract.infrastructure.core.jersey.converter.DateJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.ExternalIdJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.JsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.OffsetDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonDeserializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonSerializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JacksonLocalDateArrayModule; +import org.junit.jupiter.api.Test; +import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder; +import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.node.ObjectNode; + +/** + * Holds the Jackson 3 mapper that stores commands to what the Jackson 2 mapper behind Jersey does. + * + *

+ * The two meet on the idempotent-replay path. A command's response is written to the command table by Jackson 3; when + * the same request arrives again under the same idempotency key, that stored JSON is read back into an object and + * returned to the client, where Jersey renders it with Jackson 2. The client is entitled to receive exactly the bytes + * it received the first time, so a disagreement anywhere in that loop is a defect — and a quiet one, because both + * halves succeed. + * + *

+ * Since a replay rehydrates the stored object and lets the web layer render it, correctness of the replayed bytes rests + * on the round trip rather than on these two mappers agreeing — {@code CommandReplayRehydrationTest} is what covers + * that. What is checked here is that the command table holds what the API would have sent, which keeps a stored row + * legible against the answer it belongs to and keeps the text comparison in {@code matchesStoredRequest} meaningful. + * The exception is masking, which is load-bearing: without it a credential reaches the table in the clear. + */ +class JacksonWireFormatEquivalenceTest { + + /** What Jersey renders responses with. */ + private final com.fasterxml.jackson.databind.ObjectMapper api = apiObjectMapper(); + + /** What the command store reads and writes with. */ + private final ObjectMapper commandStore = new Jackson3ObjectMapperConfig().jackson3ObjectMapper(); + + private static com.fasterxml.jackson.databind.ObjectMapper apiObjectMapper() { + List> converters = List.of(new LocalDateTimeJsonConverter(), new OffsetDateTimeJsonConverter(), + new LocalTimeJsonConverter(), new DateJsonConverter(), new ExternalIdJsonConverter()); + + List> serializers = new ArrayList<>(converters.stream().map(JacksonSerializerAdapter::new).toList()); + List> deserializers = new ArrayList<>(converters.stream().map(JacksonDeserializerAdapter::new).toList()); + + com.fasterxml.jackson.databind.ObjectMapper objectMapper = new Jackson2ObjectMapperBuilder() // + .serializers(serializers.toArray(new JsonSerializer[0])) // + .serializationInclusion(JsonInclude.Include.NON_NULL) // + .deserializers(deserializers.toArray(new JsonDeserializer[0])) // + .featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // + .featuresToEnable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS) // + .build(); + + objectMapper.registerModule(new JacksonLocalDateArrayModule()); + + return objectMapper; + } + + /** + * What {@code CommandJsonMapper} does to a command's request and response: object to node on the way into the + * table, node back to object on the way out. + */ + private T throughTheCommandStore(T value, Class type) { + ObjectNode stored = commandStore.convertValue(value, ObjectNode.class); + + return commandStore.convertValue(stored, type); + } + + @Test + void aReplayedResponseIsIdenticalToTheOriginal() throws Exception { + Everything response = JacksonWireFormatCharacterizationTest.populated(); + + assertEquals(api.writeValueAsString(response), api.writeValueAsString(throughTheCommandStore(response, Everything.class)), + "A response replayed from the command table must reach the client as the same bytes it sent the first time."); + } + + @Test + void theLegacyArrayFormatSurvivesTheCommandStore() throws Exception { + Legacy response = new Legacy("legacy", LocalDate.of(2026, 10, 5)); + + assertEquals(api.writeValueAsString(response), api.writeValueAsString(throughTheCommandStore(response, Legacy.class)), + "A bean on the legacy LocalDate format must replay in that format too."); + } + + @Test + void whatTheCommandStoreWritesIsWhatTheApiWrites() throws Exception { + Everything response = JacksonWireFormatCharacterizationTest.populated(); + + assertEquals(api.writeValueAsString(response), commandStore.writeValueAsString(response), + "The JSON stored for a command should read the same as the JSON the client was sent."); + } + + @Test + void bothReadTheSamePayloadToTheSameObject() throws Exception { + String request = api.writeValueAsString(JacksonWireFormatCharacterizationTest.populated()); + + assertEquals(api.readValue(request, Everything.class), commandStore.readValue(request, Everything.class), + "A stored request must deserialise to the same object the API would have built from it."); + } + + @Test + void anAbsentValueIsOmittedByBoth() throws Exception { + Everything sparse = Everything.builderOfText("only"); + + assertEquals(api.writeValueAsString(sparse), commandStore.writeValueAsString(sparse), + "Null properties are left out of responses; the stored copy must leave them out too."); + } + + @Test + void credentialsAreMaskedBeforeTheyReachTheCommandTable() throws Exception { + String stored = commandStore.writeValueAsString(JacksonWireFormatCharacterizationTest.populated()); + + assertFalse(stored.contains("secret-value"), + "@JsonSerialize(using = MaskedValueSerializer.class) is a Jackson 2 annotation, so Jackson 3 cannot see it. " + + "Without the module reapplying it, external-service credentials land in the command table in the clear."); + } + + @Test + void maskingACredentialTwiceLeavesItUnchanged() throws Exception { + Everything response = JacksonWireFormatCharacterizationTest.populated(); + + assertEquals(api.writeValueAsString(response), api.writeValueAsString(throughTheCommandStore(response, Everything.class)), + "The stored copy is already masked, so replaying it masks it a second time. That has to be a no-op, " + + "or the replayed response would differ from the first one."); + } + + @Test + void theTypesNoConverterCoversAgreeToo() throws Exception { + assertEquals(api.writeValueAsString(everyOtherType()), commandStore.writeValueAsString(everyOtherType()), + "These ride on Jackson's own defaults, several of which changed between 2 and 3."); + } + + @Test + void theTypesNoConverterCoversSurviveTheCommandStore() throws Exception { + UncoveredTypes response = everyOtherType(); + + assertEquals(api.writeValueAsString(response), api.writeValueAsString(throughTheCommandStore(response, UncoveredTypes.class)), + "A response built from these must replay unchanged as well."); + } + + private static UncoveredTypes everyOtherType() { + return new UncoveredTypes(ZonedDateTime.parse("2026-10-05T11:22:33.123456789Z"), Instant.parse("2026-10-05T11:22:33.123456789Z"), + Duration.ofSeconds(90, 500), Period.of(1, 2, 3), MonthDay.of(10, 5), YearMonth.of(2026, 10), Year.of(2026), + DayOfWeek.MONDAY, Month.OCTOBER, new BigDecimal("12345678901234567890.12345678901"), new BigDecimal("1.50"), + new BigInteger("123456789012345678901234567890"), 1.5d, 2.5f, Long.MAX_VALUE, 7, + UUID.fromString("00000000-0000-0000-0000-000000000001"), "text", + List.of(LocalDate.of(2026, 1, 2), LocalDate.of(2026, 1, 3)), Map.of("only", LocalDate.of(2026, 1, 2))); + } + + /** + * The types no custom converter covers, which are therefore written by whatever each Jackson version does by + * default — {@code WRITE_DATES_AS_TIMESTAMPS} and {@code WRITE_DURATIONS_AS_TIMESTAMPS} both changed, and + * {@link Month} changed in a way no feature flag undoes. + */ + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class UncoveredTypes { + + private ZonedDateTime zonedDateTime; + private Instant instant; + private Duration duration; + private Period period; + private MonthDay monthDay; + private YearMonth yearMonth; + private Year year; + private DayOfWeek dayOfWeek; + private Month month; + private BigDecimal precise; + private BigDecimal amount; + private BigInteger bigInteger; + private Double doubleValue; + private Float floatValue; + private Long reference; + private Integer count; + private UUID uuid; + private String text; + private List dates; + private Map datesByName; + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jersey/JacksonWireFormatCharacterizationTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jersey/JacksonWireFormatCharacterizationTest.java new file mode 100644 index 00000000000..08d812c4a49 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jersey/JacksonWireFormatCharacterizationTest.java @@ -0,0 +1,209 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jersey; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonDeserializer; +import com.fasterxml.jackson.databind.JsonSerializer; +import com.fasterxml.jackson.databind.MapperFeature; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.annotation.JsonSerialize; +import java.math.BigDecimal; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.LocalTime; +import java.time.OffsetDateTime; +import java.util.ArrayList; +import java.util.Date; +import java.util.List; +import lombok.AllArgsConstructor; +import lombok.Data; +import lombok.NoArgsConstructor; +import org.apache.fineract.infrastructure.core.domain.ExternalId; +import org.apache.fineract.infrastructure.core.jersey.converter.DateJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.ExternalIdJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.JsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.OffsetDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonDeserializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonSerializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.MaskedValueSerializer; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JacksonLocalDateArrayModule; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JsonLocalDateArrayFormat; +import org.junit.jupiter.api.Test; +import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder; + +/** + * Pins the exact JSON the REST API produces and accepts. + * + *

+ * These strings are not a specification anyone wrote down; they are what the application has always sent, and clients + * have been built against them. Every value below was captured from the running mapper rather than reasoned out, so a + * failure here means the wire format moved — which is a breaking change for every caller, whatever caused it. + */ +public class JacksonWireFormatCharacterizationTest { + + private final ObjectMapper mapper = webObjectMapper(); + + /** Built exactly as {@link JerseyJacksonConverterConfig} builds the mapper Jersey serialises responses with. */ + private static ObjectMapper webObjectMapper() { + List> converters = List.of(new LocalDateTimeJsonConverter(), new OffsetDateTimeJsonConverter(), + new LocalTimeJsonConverter(), new DateJsonConverter(), new ExternalIdJsonConverter()); + + List> serializers = new ArrayList<>(converters.stream().map(JacksonSerializerAdapter::new).toList()); + List> deserializers = new ArrayList<>(converters.stream().map(JacksonDeserializerAdapter::new).toList()); + + ObjectMapper objectMapper = new Jackson2ObjectMapperBuilder() // + .serializers(serializers.toArray(new JsonSerializer[0])) // + .serializationInclusion(JsonInclude.Include.NON_NULL) // + .deserializers(deserializers.toArray(new JsonDeserializer[0])) // + .featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // + .featuresToEnable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS) // + .build(); + + objectMapper.registerModule(new JacksonLocalDateArrayModule()); + + return objectMapper; + } + + @Test + void everyHandledTypeSerialisesToItsEstablishedShape() throws Exception { + assertEquals(""" + {"text":"hello","flag":true,"count":7,"reference":9223372036854775807,\ + "amount":1.50,"precise":12345678901234567890.12345678901,"status":"ACTIVE",\ + "localDate":"2026-10-05","localDateTime":"2026-10-05T11:22:33.123456789",\ + "offsetDateTime":"2026-10-05T11:22:33.123456789Z","localTime":"11:22:33.123456789",\ + "date":"2026-10-05T11:22:33Z","externalId":"ext-1","secret":"s*******alue",\ + "nested":{"text":"inner","localDate":"2026-01-02"},"dates":[[2026,1,2],[2026,1,3]]}""", + mapper.writeValueAsString(populated()), "The JSON the API produces must not change."); + // note the asymmetry: a LocalDate property is written as a string, but a List is written as arrays, + // because the serializer modifier only reassigns properties whose raw type is LocalDate. Clients depend on + // both shapes as they are. + } + + @Test + void nullsAreOmittedRatherThanWritten() throws Exception { + assertEquals("{\"text\":\"only\"}", mapper.writeValueAsString(Everything.builderOfText("only")), + "Null properties are left out of responses; writing them would change every payload."); + } + + @Test + void aBeanMarkedLegacyKeepsTheArrayShapeForLocalDate() throws Exception { + assertEquals("{\"text\":\"legacy\",\"localDate\":[2026,10,5]}", + mapper.writeValueAsString(new Legacy("legacy", LocalDate.of(2026, 10, 5))), + "Beans marked for the legacy format must keep writing LocalDate as a [year, month, day] array."); + } + + @Test + void whatTheApiAcceptsIsUnchanged() throws Exception { + var parsed = mapper.readValue(""" + {"text":"hello","localDate":"2026-10-05","localDateTime":"2026-10-05T11:22:33.123456789",\ + "offsetDateTime":"2026-10-05T11:22:33.123456789Z","localTime":"11:22:33.123456789",\ + "date":"2026-10-05T11:22:33Z","externalId":"ext-1","amount":1.50,"unknown":"ignored"}""", Everything.class); + + assertEquals("hello", parsed.getText()); + assertEquals(LocalDate.of(2026, 10, 5), parsed.getLocalDate()); + assertEquals(LocalDateTime.parse("2026-10-05T11:22:33.123456789"), parsed.getLocalDateTime()); + assertEquals(OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z"), parsed.getOffsetDateTime()); + assertEquals(LocalTime.parse("11:22:33.123456789"), parsed.getLocalTime()); + assertEquals("ext-1", parsed.getExternalId().getValue()); + assertEquals(new BigDecimal("1.50"), parsed.getAmount(), "A decimal must keep its scale when read."); + assertNull(parsed.getStatus(), "An absent property stays null."); + } + + @Test + void anUnknownPropertyIsIgnoredRatherThanRejected() throws Exception { + assertEquals("hello", mapper.readValue("{\"text\":\"hello\",\"nope\":1}", Everything.class).getText()); + } + + @Test + void anEnumIsAcceptedWhateverItsCase() throws Exception { + assertEquals(Status.ACTIVE, mapper.readValue("{\"status\":\"active\"}", Everything.class).getStatus()); + } + + public static Everything populated() { + var nested = new Nested("inner", LocalDate.of(2026, 1, 2)); + + return new Everything("hello", true, 7, Long.MAX_VALUE, new BigDecimal("1.50"), new BigDecimal("12345678901234567890.12345678901"), + Status.ACTIVE, LocalDate.of(2026, 10, 5), LocalDateTime.parse("2026-10-05T11:22:33.123456789"), + OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z"), LocalTime.parse("11:22:33.123456789"), + Date.from(java.time.Instant.parse("2026-10-05T11:22:33Z")), new ExternalId("ext-1"), "secret-value", nested, + List.of(LocalDate.of(2026, 1, 2), LocalDate.of(2026, 1, 3))); + } + + public enum Status { + ACTIVE, CLOSED + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class Everything { + + private String text; + private Boolean flag; + private Integer count; + private Long reference; + private BigDecimal amount; + private BigDecimal precise; + private Status status; + private LocalDate localDate; + private LocalDateTime localDateTime; + private OffsetDateTime offsetDateTime; + private LocalTime localTime; + private Date date; + private ExternalId externalId; + @JsonSerialize(using = MaskedValueSerializer.class) + private String secret; + private Nested nested; + private List dates; + + public static Everything builderOfText(String text) { + var everything = new Everything(); + + everything.setText(text); + + return everything; + } + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class Nested { + + private String text; + private LocalDate localDate; + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + @JsonLocalDateArrayFormat + public static class Legacy { + + private String text; + private LocalDate localDate; + } +} From 20cc1c24d246e8953c5e93d14ef1b2a8518654d9 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Mon, 9 Nov 2026 19:07:29 +0000 Subject: [PATCH 04/11] FINERACT-2485: Replay a completed command from its stored result object A repeat of a completed command is answered by rehydrating the stored result and handing it back through the dispatcher, so the resource and the web layer render it exactly as they rendered the original. Nothing about the original response has to be recorded for the two to match, which removes the stored status code for successful commands. The response capture now fills gaps only, enforced in SQL (response IS NULL): the status and the rendered answer are recorded only for a command that produced no result of its own. A stored result that cannot be reconstructed is answered 409 stating why, rather than a 500 or an empty 200, and an answer that cannot be stored is logged so that it stays recoverable. Every write to the command row is retried, including claiming the key and recording the answer. The retry policy is defined once rather than repeated across 47 instances, and covers everything non-deterministic while ignoring constraint violations explicitly. Attempt tracking is removed. --- .../DisruptorCommandDispatcher.java | 29 +- .../IdempotencyCommandConstants.java | 7 +- .../hook/IdempotencyCheckCommandHook.java | 132 ++++++- .../hook/IdempotencyKeyHeaderCommandHook.java | 5 +- .../IdempotencyCommandAutoConfiguration.java | 31 +- .../IdempotencyCommandExceptionHandler.java | 50 +++ .../IdempotencyCommandExceptionMapper.java | 53 +++ .../web/IdempotencyResponseCaptureFilter.java | 138 ++++++++ .../idempotency/IdempotencyEndToEndTest.java | 275 +++++++++++++++ .../idempotency/TestConfiguration.java | 38 ++ .../hook/IdempotencyCheckCommandHookTest.java | 202 +++++++++++ .../IdempotencyResponseCaptureFilterTest.java | 144 ++++++++ .../resources/application-test.properties | 45 +++ .../org/apache/fineract/messages.properties | 71 ++++ fineract-command-jdbc/dependencies.gradle | 4 + .../command/jdbc/store/JdbcCommandStore.java | 105 +++++- .../jdbc/store/domain/CommandEntity.java | 9 + .../store/domain/JdbcCommandRepository.java | 38 ++ .../jdbc/store/mapping/JsonCommandMapper.java | 6 +- .../command/module-changelog-master.xml | 1 + .../parts/0003_idempotency_key_unique.xml | 46 ++- .../parts/0004_command_response_cache.xml | 37 ++ .../CommandIdempotencyKeyMigrationTest.java | 174 ++++++++++ .../jdbc/JdbcCommandStoreRetryTest.java | 122 +++++++ .../command/jdbc/JdbcCommandStoreTest.java | 325 ++++++++++++++++++ .../command/jdbc/RetryPolicyTest.java | 90 +++++ .../command-migration-test-changelog.xml | 76 ++++ .../test/sample/api/DummyApiController.java | 15 + .../test/sample/data/DummyRequest.java | 25 +- .../fineract/command/core/CommandReplay.java | 35 ++ .../fineract/command/core/CommandStore.java | 30 +- .../AbstractCommandIdempotencyException.java | 57 +++ .../CommandIdempotencyConflictException.java | 37 ++ .../CommandIdempotencyFailedException.java | 31 ++ ...CommandIdempotencyInProgressException.java | 33 ++ .../CommandIdempotencyProcessedException.java | 30 ++ .../command/util/ServletHeaderUtil.java | 26 ++ .../command/CommandSampleApiTest.java | 22 +- .../CommandIdempotencyExceptionTest.java | 74 ++++ .../UpdateWorkingDaysCommandHandler.java | 6 + .../src/main/resources/application.properties | 15 +- .../CommandHandlerRetryCoverageTest.java | 98 ++++++ ...tencyCommandExceptionMapperJerseyTest.java | 123 +++++++ .../resources/application-test.properties | 4 + 44 files changed, 2839 insertions(+), 75 deletions(-) create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapper.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java create mode 100644 fineract-command-idempotency/src/test/resources/application-test.properties create mode 100644 fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml create mode 100644 fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java create mode 100644 fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java create mode 100644 fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java create mode 100644 fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/RetryPolicyTest.java create mode 100644 fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java create mode 100644 fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapperJerseyTest.java diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java index 102164915e0..971251d4a11 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java @@ -56,9 +56,7 @@ public class DisruptorCommandDispatcher implements CommandDispatcher, Closeable public Supplier dispatch(Command command) { requireNonNull(command, "Command must not be null"); - CommandEvent processedEvent = next(CommandContext.builder().command(command).build()); - - var future = processedEvent.getFuture(); + var future = next(CommandContext.builder().command(command).build()); return future::join; } @@ -73,17 +71,28 @@ void onStartup() { disruptor.start(); } + /** + * Ring buffer slots are reused, so each command needs a fresh future. It has to be created and handed back to the + * caller before the slot is published: from that moment the slot belongs to the consumer, which may already + * have completed and replaced anything read from it afterwards. + */ @SuppressWarnings({ "unchecked" }) - private CommandEvent next(CommandContext ctx) { + private CompletableFuture next(CommandContext ctx) { var ringBuffer = disruptor.getRingBuffer(); var sequenceId = ringBuffer.next(); - CommandEvent event = ringBuffer.get(sequenceId); - event.setContext(ctx); - ringBuffer.publish(sequenceId); + try { + CommandEvent event = ringBuffer.get(sequenceId); + var future = new CompletableFuture(); + + event.setContext(ctx); + event.setFuture(future); - return event; + return future; + } finally { + ringBuffer.publish(sequenceId); + } } @Getter @@ -91,7 +100,7 @@ private CommandEvent next(CommandContext ctx) { public static class CommandEvent { private CommandContext context; - private CompletableFuture future = new CompletableFuture<>(); + private CompletableFuture future; } @RequiredArgsConstructor @@ -126,8 +135,6 @@ public void onEvent(CommandEvent event, long sequence, boolean endOfBatch) { hookManager.error(ctx); event.getFuture().completeExceptionally(e); - } finally { - event.setFuture(new CompletableFuture<>()); } } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java index 3d544da6783..a0280b47f5d 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java @@ -30,7 +30,12 @@ private IdempotencyCommandConstants() {} + ".hook-key-header-pre"; public static final String COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + ".hook-check-pre"; public static final String COMMAND_IDEMPOTENCY_PROPERTY_KEY_HEADER_NAME = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + ".key-header-name"; - public static final String COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE = "org.apache.fineract.command.idempotency.hook"; + public static final String COMMAND_IDEMPOTENCY_BASE_PACKAGE = "org.apache.fineract.command.idempotency"; + public static final String COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE = COMMAND_IDEMPOTENCY_BASE_PACKAGE + ".hook"; + public static final String COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE = COMMAND_IDEMPOTENCY_BASE_PACKAGE + ".web"; + public static final String COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE = COMMAND_IDEMPOTENCY_BASE_PACKAGE + ".check"; + /** Marks the request that claimed a key, so the capture filter knows whose answer it is looking at. */ + public static final String COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE = "fineract.command.idempotency.claimedKey"; public static final int COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE = 20; public static final int COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE = 21; } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java index f1d0e8b5eaf..6f5aaaa259a 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -18,24 +18,38 @@ */ package org.apache.fineract.command.idempotency.hook; +import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; +import java.util.Map; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.core.CommandReplay; import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.exception.CommandIdempotencyConflictException; +import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; +import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; +import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.apache.fineract.command.util.ServletHeaderUtil; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; +import org.springframework.web.context.request.RequestAttributes; +import org.springframework.web.context.request.RequestContextHolder; @Slf4j @RequiredArgsConstructor @Component @Order(COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE) -@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true") +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) final class IdempotencyCheckCommandHook implements CommandHookBefore { private final CommandStore store; @@ -43,26 +57,116 @@ final class IdempotencyCheckCommandHook implements CommandHookBefore ctx) { var command = ctx.getCommand(); + var key = command.getIdempotencyKey(); - if (StringUtils.isNotEmpty(command.getIdempotencyKey())) { - var exists = store.existsByKey(command.getIdempotencyKey()); + if (StringUtils.isEmpty(key)) { + return; + } + + // claiming the key is what detects duplicates: the unique constraint means exactly one concurrent request can + // win, whereas a read-only check followed by execution lets every racer through + if (store.claim(command)) { + rememberClaimForResponseCapture(key); + + return; + } + + // the command is never executed again, so it is not audited again either; the claimed row already owns this key + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + + var replay = replayFor(key); + + log.warn("Duplicate idempotency key detected: {} (state = {}, user = {}, ip = {})", key, replay.state(), + command.getInitiatedByUsername(), command.getIpAddress()); - if (exists) { - ctx.setSkipExecution(true); - ctx.setSkipHooks(true); + if (UNDER_PROCESSING.equals(replay.state())) { + // the original has not finished, so there is nothing to replay yet and retrying is the right thing to do + throw new CommandIdempotencyInProgressException(key, replay.response()); + } + + if (!store.matchesStoredRequest(key, command.getPayload())) { + // replaying here would answer a question that was never asked + throw new CommandIdempotencyConflictException(key, null); + } - var isSameRequestClass = store.checkRequestInstanceByKey(command.getIdempotencyKey(), command.getPayload().getClass()); + if (ERROR.equals(replay.state())) { + // a repeat of a failed command fails exactly the way the original did + throw new CommandIdempotencyFailedException(key, replay.statusCode(), replay.response()); + } - log.warn("Duplicate key detected: {} (same request class = {})", command.getIdempotencyKey(), isSameRequestClass); + if (PROCESSED.equals(replay.state())) { + replayProcessed(ctx, key, replay); - if (isSameRequestClass) { - var response = store.getResponseByKey(command.getIdempotencyKey()); + return; + } + + throw new CommandIdempotencyConflictException(key, replay.response()); + } + + /** + * Reads what was stored for a key, turning a result that cannot be reconstructed into a rejection. + * + *

+ * A stored result that will not rehydrate - a type that has been renamed or removed since, a field that no longer + * deserialises - leaves the original answer unreachable. Letting that surface as a server error would say the + * request failed, and answering with an empty body would say it succeeded with no content; both are untrue. The key + * has been used and its answer cannot be produced, so the request is refused and told why. + */ + private CommandReplay replayFor(String key) { + try { + return store.getReplayByKey(key); + } catch (RuntimeException e) { + log.error("Cannot reconstruct the stored result for idempotency key {}", key, e); + + throw new CommandIdempotencyConflictException(key, + Map.of("idempotencyKey", key, "error", + "The result stored under this idempotency key cannot be reconstructed, so the original answer " + + "cannot be replayed. Retry with a new idempotency key."), + e); + } + } + + /** + * Answers a repeat of a command that completed. + * + *

+ * Where the command stored a result of its own, that result is handed back through the dispatcher rather than + * thrown: {@code skipExecution} makes the dispatcher return it, the resource method returns it as it returned the + * original, and the web layer renders it with the serializer and the status it used the first time. Nothing about + * the original answer has to have been recorded for that to come out identical - not the status, not the bytes. + * + *

+ * Only a command that stored no result of its own falls back to the answer that was captured as it went out, and + * that is text rather than an object, so it has to be thrown with the status recorded alongside it. + */ + private void replayProcessed(CommandContext ctx, String key, CommandReplay replay) { + var response = replay.response(); + + if (response == null || response instanceof String) { + throw new CommandIdempotencyProcessedException(key, replay.statusCode(), response); + } + + markServedFromCache(key); + + ctx.setResponse(response); + } + + /** + * The replay header is set here rather than by an exception mapper, because a replay answered from the command's + * own result never reaches one - it leaves through the ordinary return path. + */ + private static void markServedFromCache(String key) { + if (!ServletHeaderUtil.setResponseHeader(IDEMPOTENT_CACHE_HEADER, "true")) { + log.warn("Replaying idempotency key {} outside an HTTP response, so it is not marked as served from cache", key); + } + } - ctx.setResponse(response); - } + private static void rememberClaimForResponseCapture(String key) { + var attributes = RequestContextHolder.getRequestAttributes(); - // TODO: else throw an exception? - } + if (attributes != null) { + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, key, RequestAttributes.SCOPE_REQUEST); } } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java index 5981fd47c74..5c7fd9414e0 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java @@ -36,7 +36,7 @@ @RequiredArgsConstructor @Component @Order(COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE) -@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE, havingValue = "true") +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE, havingValue = "true", matchIfMissing = true) final class IdempotencyKeyHeaderCommandHook implements CommandHookBefore { private final IdempotencyCommandProperties properties; @@ -46,7 +46,8 @@ public void onBefore(CommandContext ctx) { var command = ctx.getCommand(); if (StringUtils.isEmpty(command.getIdempotencyKey())) { - command.setIdempotencyKey(getHeader(properties.getKeyHeaderName(), true)); + // header only: an idempotency key in the query string would be copied into access and proxy logs + command.setIdempotencyKey(getHeader(properties.getKeyHeaderName(), false)); } } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java index 6a514965317..866fdd2b93d 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java @@ -20,15 +20,40 @@ import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE; +import org.apache.fineract.command.core.CommandStore; import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.web.IdempotencyResponseCaptureFilter; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.boot.web.servlet.FilterRegistrationBean; +import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; +import org.springframework.core.Ordered; @AutoConfiguration @EnableConfigurationProperties({ IdempotencyCommandProperties.class }) -@ComponentScan(COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE) -@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_ENABLED, havingValue = "true") -public class IdempotencyCommandAutoConfiguration {} +@ComponentScan({ COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE, COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE }) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_ENABLED, havingValue = "true", matchIfMissing = true) +public class IdempotencyCommandAutoConfiguration { + + /** + * Fills in what a command could not record about its own answer: the status it was sent with, always, and the body + * itself only when the command stored no result of its own - a failure, or an answer that is not JSON. Ordered + * early so that it sees the response as the client will, and it steps aside entirely for requests that carry no + * key. + */ + @Bean + @ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) + FilterRegistrationBean idempotencyResponseCaptureFilter(CommandStore store, + IdempotencyCommandProperties properties) { + var registration = new FilterRegistrationBean<>(new IdempotencyResponseCaptureFilter(store, properties)); + + registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 100); + + return registration; + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java new file mode 100644 index 00000000000..18dfa7b773c --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java @@ -0,0 +1,50 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; + +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.Order; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.ExceptionHandler; +import org.springframework.web.bind.annotation.RestControllerAdvice; + +/** + * The Spring MVC counterpart of {@link IdempotencyCommandExceptionMapper}. Endpoints built on the command framework + * exist on both web stacks, and a repeated request has to be answered the same way whichever one serves it. + *

+ * Ordered ahead of any application-wide handler, which would otherwise turn a replay into an error response. + */ +@Slf4j +@Order(Ordered.HIGHEST_PRECEDENCE) +@RestControllerAdvice +public class IdempotencyCommandExceptionHandler { + + @ExceptionHandler(AbstractCommandIdempotencyException.class) + public ResponseEntity handle(AbstractCommandIdempotencyException exception) { + log.warn("Replaying idempotency key {} with status {}", exception.getIdempotencyKey(), exception.getStatusCode()); + + return ResponseEntity.status(exception.getStatusCode()).header(IDEMPOTENT_CACHE_HEADER, "true") + .contentType(MediaType.APPLICATION_JSON).body(exception.getResponse()); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapper.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapper.java new file mode 100644 index 00000000000..12cd0f5cb77 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapper.java @@ -0,0 +1,53 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; + +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; +import jakarta.ws.rs.ext.ExceptionMapper; +import jakarta.ws.rs.ext.Provider; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException; +import org.springframework.context.annotation.Scope; +import org.springframework.stereotype.Component; + +/** + * Answers a repeated request with what the original one was answered with: the same status, the command's own result + * object, plus a header saying it was served from the command store rather than executed again. + * + *

+ * The entity is the rehydrated result, not stored text, so Jersey renders the replay through the very mapper that + * rendered the original answer. That is what makes the two identical, rather than an agreement between two mappers. + */ +@Slf4j +@Provider +@Component +@Scope("singleton") +public class IdempotencyCommandExceptionMapper implements ExceptionMapper { + + @Override + public Response toResponse(AbstractCommandIdempotencyException exception) { + log.warn("Replaying idempotency key {} with status {}", exception.getIdempotencyKey(), exception.getStatusCode()); + + return Response.status(exception.getStatusCode()).entity(exception.getResponse()).header(IDEMPOTENT_CACHE_HEADER, "true") + .type(MediaType.APPLICATION_JSON).build(); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java new file mode 100644 index 00000000000..977fc51ce5d --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java @@ -0,0 +1,138 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; + +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.util.Locale; +import lombok.NonNull; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.util.StringUtils; +import org.springframework.web.filter.OncePerRequestFilter; +import org.springframework.web.util.ContentCachingResponseWrapper; + +/** + * Records what a request that claimed an idempotency key was answered with, for the parts the command itself could not + * record. + * + *

+ * A command that produced a result stores that result as an object, and a repeat is answered by rehydrating it and + * letting the web layer render it again - which is what makes a replay identical to the original. So what is captured + * here never replaces a stored result; it only fills in what is missing. The status code is always missing, because the + * command layer has no notion of one. The body is missing only when the command produced no result of its own: a + * failure, whose answer is rendered from an exception, and an answer that is not JSON. + */ +@Slf4j +@RequiredArgsConstructor +public class IdempotencyResponseCaptureFilter extends OncePerRequestFilter { + + private final CommandStore store; + + private final IdempotencyCommandProperties properties; + + /** + * A request that carries no idempotency key can claim nothing, so there is nothing to record for it. Skipping it + * here is what keeps this off the hot path: everything else on the API is served without its response being + * buffered. + */ + @Override + protected boolean shouldNotFilter(@NonNull HttpServletRequest request) { + return !StringUtils.hasText(request.getHeader(properties.getKeyHeaderName())); + } + + @Override + protected void doFilterInternal(@NonNull HttpServletRequest request, @NonNull HttpServletResponse response, + @NonNull FilterChain filterChain) throws ServletException, IOException { + var wrapper = new ContentCachingResponseWrapper(response); + + try { + filterChain.doFilter(request, wrapper); + } finally { + record(request, wrapper); + + // the body has been read out of the wrapper, so it has to be written on to the real response + wrapper.copyBodyToResponse(); + } + } + + private void record(HttpServletRequest request, ContentCachingResponseWrapper wrapper) { + var key = (String) request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE); + + if (!StringUtils.hasText(key)) { + // no command claimed a key during this request, so there is nothing to replay later + return; + } + + var body = replayableBody(key, wrapper); + + try { + store.recordResponse(key, wrapper.getStatus(), body); + } catch (RuntimeException e) { + // the command itself has been processed and answered; failing here must not change that outcome. The + // record is left claiming an outcome it cannot produce, so the failure is logged loudly - but with the + // shape of the answer rather than the answer itself, which on this API carries customer data. + log.error( + "Unable to record the response for idempotency key {} (status {}, {} {} bytes); a repeat of this key " + + "cannot be answered from it", + key, wrapper.getStatus(), describe(wrapper.getContentType()), + body == null ? 0 : body.getBytes(StandardCharsets.UTF_8).length, e); + } + } + + private static String describe(String contentType) { + return contentType == null ? "untyped" : contentType; + } + + /** + * Only a JSON body is worth keeping: the response is kept in a JSON column, and anything else - a file download, an + * empty body - could not be read back. The status code is still recorded for those. + */ + private String replayableBody(String key, ContentCachingResponseWrapper wrapper) { + var body = new String(wrapper.getContentAsByteArray(), StandardCharsets.UTF_8); + + if (!StringUtils.hasText(body)) { + return null; + } + + var contentType = wrapper.getContentType(); + + if (contentType == null || !contentType.toLowerCase(Locale.ROOT).contains("json")) { + // the response column holds JSON and nothing else, so this answer cannot be stored. Only its shape is + // logged: the body of a response on this API can carry customer data, and keeping that out of places it + // does not belong is the point of the masking this module does elsewhere. + log.warn( + "Cannot store a {} answer for idempotency key {} (status {}, {} bytes); a repeat will be answered " + + "with the status and an empty body", + describe(contentType), key, wrapper.getStatus(), body.getBytes(StandardCharsets.UTF_8).length); + + return null; + } + + return body; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java new file mode 100644 index 00000000000..4e836622571 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java @@ -0,0 +1,275 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.stream.IntStream; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.junit.jupiter.api.Test; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.web.client.RestTemplate; + +/** + * Drives the whole thing over HTTP, which is the only level at which the behaviour this feature promises is visible: + * the status code, the body and the replay header a repeated request is answered with. + *

+ * These are the same guarantees the old command processing gives, as pinned by + * {@code org.apache.fineract.integrationtests.IdempotencyTest}. + */ +@Slf4j +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +public class IdempotencyEndToEndTest extends CommandBaseTest { + + @LocalServerPort + private int port; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @org.springframework.beans.factory.annotation.Autowired + private CommandStore store; + + @org.springframework.beans.factory.annotation.Autowired + private JdbcCommandRepository repository; + + @Test + public void aRequestWithoutAKeyIsNeverTreatedAsARepeat() { + var first = post("/sync", "hello", null); + var second = post("/sync", "hello", null); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "A request without a key must be processed."); + assertTrue(second.getStatusCode().is2xxSuccessful(), "A second request without a key must be processed too."); + assertFalse(servedFromCache(second), "Nothing can be replayed without an idempotency key."); + } + + @Test + public void theFirstRequestIsProcessedAndTheRepeatIsReplayed() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + assertFalse(servedFromCache(first), "The first request is executed, not replayed."); + assertNotNull(first.getBody(), "The first request must return a body."); + + var second = post("/sync", "hello", key); + + assertTrue(servedFromCache(second), "A repeat must be marked as served from the command store."); + assertEquals(first.getStatusCode(), second.getStatusCode(), "A repeat must be answered with the original status."); + assertEquals(first.getBody(), second.getBody(), "A repeat must be answered with the original body."); + } + + @Test + public void aRepeatOfAFailedRequestFailsTheSameWay() { + var key = UUID.randomUUID().toString(); + + // this endpoint always fails, so the command is stored as failed + var first = post("/error", "boom", key); + + assertTrue(first.getStatusCode().is4xxClientError(), "The request must fail, got " + first.getStatusCode() + " " + first.getBody()); + assertFalse(servedFromCache(first), "The first failure is produced, not replayed."); + + var second = post("/error", "boom", key); + + assertTrue(servedFromCache(second), "A repeat of a failure must be marked as served from the command store."); + assertEquals(first.getStatusCode(), second.getStatusCode(), "A repeat must fail with the original status."); + assertEquals(first.getBody(), second.getBody(), "A repeat must fail with the original body."); + } + + @Test + public void aThirdRepeatIsAnsweredLikeTheSecond() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + var second = post("/sync", "hello", key); + var third = post("/sync", "hello", key); + + // the earlier implementation accumulated rows per repeat and broke on the third request + assertEquals(first.getStatusCode(), third.getStatusCode(), "Repeats must stay stable however often they are made."); + assertEquals(second.getBody(), third.getBody(), "Repeats must stay stable however often they are made."); + assertTrue(servedFromCache(third), "Every repeat is served from the command store."); + } + + @Test + public void aKeyReusedForADifferentRequestIsRejected() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + var different = post("/sync", "something-else", key); + + assertEquals(409, different.getStatusCode().value(), "Reusing a key for a different request must not replay the first answer."); + } + + @Test + public void aKeyIsUniqueAcrossCommandsNotOnlyWithinOne() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + + // deliberately stricter than the old command processing, which scopes a key by action and entity name and so + // would execute this. A key here identifies one command for the whole tenant. + var otherCommand = post("/error", "boom", key); + + assertEquals(409, otherCommand.getStatusCode().value(), + "Reusing a key for a different command must be rejected, not executed and not replayed."); + } + + @Test + public void concurrentRepeatsExecuteTheCommandOnlyOnce() throws Exception { + var threads = 6; + var key = UUID.randomUUID().toString(); + var startLine = new CountDownLatch(1); + var executed = new AtomicInteger(); + var replayed = new AtomicInteger(); + var tooEarly = new AtomicInteger(); + + try (var executor = Executors.newFixedThreadPool(threads)) { + var calls = IntStream.range(0, threads).mapToObj(i -> executor.submit(() -> { + startLine.await(); + + var response = post("/sync", "hello", key); + + if (servedFromCache(response)) { + replayed.incrementAndGet(); + } else if (response.getStatusCode().value() == 425) { + tooEarly.incrementAndGet(); + } else { + executed.incrementAndGet(); + } + + return null; + })).toList(); + + startLine.countDown(); + + for (var call : calls) { + call.get(60, TimeUnit.SECONDS); + } + } + + assertEquals(1, executed.get(), "Exactly one concurrent request may execute the command."); + assertEquals(threads - 1, replayed.get() + tooEarly.get(), "Every other request must be replayed or told it is too early."); + } + + @Test + public void aRequestForACommandStillRunningIsToldItIsTooEarly() { + var key = UUID.randomUUID().toString(); + var inFlight = new DummyCommand(); + + inFlight.setPayload(DummyRequest.builder().content("hello").build()); + inFlight.setIdempotencyKey(key); + inFlight.setCreatedAt(java.time.Instant.now()); + + // claim the key without ever completing it, which is what another node mid-request looks like + store.claim(inFlight); + + var response = post("/sync", "hello", key); + + assertEquals(425, response.getStatusCode().value(), "A command that has not finished must answer 425 Too Early."); + assertTrue(servedFromCache(response), "The answer comes from the command store, so it carries the replay header."); + } + + @Test + public void oneCommandIsRecordedAndRepeatsNeverAddAnother() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + var recorded = repository.findOneByIdempotencyKey(key).orElseThrow(); + + assertEquals(CommandState.PROCESSED, recorded.getState(), "A processed command must be audited as processed."); + assertNotNull(recorded.getResponse(), "The result the command produced must be recorded."); + assertNull(recorded.getResponseStatusCode(), "A command that produced a result needs no recorded status: its " + + "repeat is answered by handing that result back, and the web layer derives the status from it."); + + post("/sync", "hello", key); + post("/sync", "hello", key); + + assertEquals(1, repository.findAll().stream().filter(e -> key.equals(e.getIdempotencyKey())).count(), + "Repeats must not add command records."); + + var afterRepeats = repository.findOneByIdempotencyKey(key).orElseThrow(); + + assertEquals(CommandState.PROCESSED, afterRepeats.getState(), "A repeat must not change the recorded outcome."); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(org.springframework.http.MediaType.APPLICATION_JSON); + + if (idempotencyKey != null) { + headers.add("Idempotency-Key", idempotencyKey); + } + + var body = content == null ? DummyRequest.builder().build() : DummyRequest.builder().content(content).build(); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, new HttpEntity<>(body, headers), + String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst(IDEMPOTENT_CACHE_HEADER)); + } + + /** + * The failure cases are part of the contract under test, so an error status has to come back as a response rather + * than as an exception. + */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java new file mode 100644 index 00000000000..29b423e0113 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java @@ -0,0 +1,38 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.boot.autoconfigure.EnableAutoConfiguration; +import org.springframework.context.annotation.ComponentScan; +import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.PropertySource; +import org.springframework.data.jdbc.repository.config.EnableJdbcRepositories; + +/** + * Wires the whole chain the way a real deployment does: the sample API, the command framework, the audit hooks, the + * JDBC store and this module. Only then does an end-to-end test say anything about how a repeated request is answered. + */ +@Slf4j +@Configuration +@EnableAutoConfiguration +@EnableJdbcRepositories(basePackages = { "org.apache.fineract.command.jdbc.store.domain" }) +@PropertySource("classpath:application-test.properties") +@ComponentScan({ "org.apache.fineract.command.jdbc.store", "org.apache.fineract.command.test.sample" }) +public class TestConfiguration {} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java new file mode 100644 index 00000000000..7be76463cd0 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -0,0 +1,202 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.CommandState.UNKNOWN; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import java.util.Map; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandReplay; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.exception.CommandIdempotencyConflictException; +import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; +import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; +import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; + +@ExtendWith(MockitoExtension.class) +class IdempotencyCheckCommandHookTest { + + private static final String KEY = "7f3a1c04-0000-0000-0000-000000000000"; + + @Mock + private CommandStore store; + + private IdempotencyCheckCommandHook hook; + + @BeforeEach + void setUp() { + hook = new IdempotencyCheckCommandHook(store); + } + + @Test + void aCommandWithoutAKeyIsNeverClaimed() { + var ctx = context(null); + + hook.onBefore(ctx); + + verifyNoInteractions(store); + assertFalse(ctx.isSkipExecution(), "A command without an idempotency key must be executed."); + } + + @Test + void winningTheClaimLetsTheCommandExecute() { + var ctx = context(KEY); + + when(store.claim(any())).thenReturn(true); + + hook.onBefore(ctx); + + assertFalse(ctx.isSkipExecution(), "The request that claims the key must be executed."); + verify(store, never()).getReplayByKey(anyString()); + } + + @Test + void anUnfinishedCommandAnswersTooEarly() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null)); + + var exception = assertThrows(CommandIdempotencyInProgressException.class, () -> hook.onBefore(ctx)); + + assertEquals(425, exception.getStatusCode(), "An unfinished command must answer 425 Too Early."); + assertTrue(ctx.isSkipExecution(), "An in-flight command must not be executed a second time."); + // the request is not compared here: there is nothing stored to compare a response against yet + verify(store, never()).matchesStoredRequest(anyString(), any()); + } + + @Test + void aProcessedCommandIsReplayedByHandingBackItsOwnResult() { + var ctx = context(KEY); + + var stored = Map.of("resourceId", 7); + + duplicate(new CommandReplay(PROCESSED, null, stored)); + when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + + hook.onBefore(ctx); + + // nothing is thrown: the dispatcher returns this to the resource, which returns it as it returned the + // original, so the web layer renders the status and the bytes exactly as it did the first time + assertSame(stored, ctx.getResponse(), "A repeat is answered with the command's own stored result."); + assertTrue(ctx.isSkipExecution(), "A duplicate command must not be executed again."); + } + + @Test + void aProcessedCommandWithOnlyACapturedAnswerIsThrownWithItsRecordedStatus() { + var ctx = context(KEY); + + // no result object to hand back, so the answer captured as it went out is replayed as the text it is, and + // the status has to come from the record because nothing else can derive it + duplicate(new CommandReplay(PROCESSED, 201, "{\"resourceId\":7}")); + when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + + var exception = assertThrows(CommandIdempotencyProcessedException.class, () -> hook.onBefore(ctx)); + + assertEquals(201, exception.getStatusCode(), "A replay must answer with the original status."); + assertEquals("{\"resourceId\":7}", exception.getResponse()); + } + + @Test + void aFailedCommandIsReplayedAsTheSameFailure() { + var ctx = context(KEY); + + var stored = Map.of("error", "bad request"); + + duplicate(new CommandReplay(ERROR, 400, stored)); + when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + + // this is what the old processing does: a repeat of a failure fails identically rather than being retried + var exception = assertThrows(CommandIdempotencyFailedException.class, () -> hook.onBefore(ctx)); + + assertEquals(400, exception.getStatusCode(), "A repeat of a failed command must fail with the original status."); + assertSame(stored, exception.getResponse(), "A repeat of a failed command must return what was stored for it."); + assertTrue(ctx.isSkipExecution(), "A failed command must not be executed again by a repeat."); + } + + @Test + void aKeyReusedForADifferentRequestConflicts() { + var ctx = context(KEY); + + duplicate(new CommandReplay(PROCESSED, 200, Map.of())); + when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(false); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), "Reusing a key for a different request is a conflict, not a replay."); + } + + @Test + void anUnrecognisedStateConflictsRatherThanGuessing() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNKNOWN, null, null)); + when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + + assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + } + + @Test + void aStoredResultThatCannotBeReconstructedIsRefusedRatherThanGuessedAt() { + var ctx = context(KEY); + + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY)).thenThrow(new IllegalStateException("Cannot rehydrate a stored command result")); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), + "The key has been used and its answer cannot be produced, which is neither a success nor a failure of this request."); + assertTrue(String.valueOf(exception.getResponse()).contains("cannot be reconstructed"), + "The answer must say what went wrong rather than coming back empty."); + } + + private void duplicate(CommandReplay replay) { + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY)).thenReturn(replay); + } + + private static CommandContext context(String key) { + var command = new Command(); + + command.setIdempotencyKey(key); + command.setPayload("request-payload"); + + return CommandContext.builder().command(command).build(); + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java new file mode 100644 index 00000000000..5668afa365e --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java @@ -0,0 +1,144 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.ArgumentMatchers.isNull; +import static org.mockito.Mockito.doThrow; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; +import org.springframework.mock.web.MockFilterChain; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.mock.web.MockHttpServletResponse; + +/** + * Covers what the filter does with an answer it cannot store. + * + *

+ * The response column holds JSON and nothing else, so an answer of any other kind is dropped and the repeat of that key + * is left with a status and an empty body. That is worth a log line, but only the shape of the answer: a response on + * this API can carry customer data, and keeping that out of the logs is the concern the masking elsewhere answers. + */ +class IdempotencyResponseCaptureFilterTest { + + private static final String KEY = "a-key"; + + private final CommandStore store = mock(CommandStore.class); + + private final IdempotencyResponseCaptureFilter filter = new IdempotencyResponseCaptureFilter(store, + IdempotencyCommandProperties.builder().build()); + + private final ListAppender captured = new ListAppender<>(); + + private Logger logger; + + @BeforeEach + void captureLogging() { + // by name rather than by class: this is deliberately another class's logger, which is what the appender + // has to attach to in order to read what the filter logged + logger = (Logger) LoggerFactory.getLogger(IdempotencyResponseCaptureFilter.class.getName()); + + captured.start(); + logger.addAppender(captured); + } + + @AfterEach + void stopCapturingLogging() { + logger.detachAppender(captured); + } + + @Test + void anAnswerThatIsNotJsonIsReportedWithoutItsBody() throws Exception { + var csv = "id,amount\n7,1.50\n"; + var response = runWith("text/csv", csv); + + verify(store).recordResponse(eq(KEY), eq(200), isNull()); + + assertFalse(logged().contains("id,amount"), "The body must not reach the log: responses here carry customer data."); + assertTrue( + logged().contains(KEY) && logged().contains("text/csv") + && logged().contains(csv.getBytes(java.nio.charset.StandardCharsets.UTF_8).length + " bytes"), + "What is logged is the shape of the answer - key, status, content type and size - so the loss is " + + "diagnosable without copying the answer into the log."); + assertEquals(csv, response.getContentAsString(), "Whatever the filter does with its copy, the client still receives the answer."); + } + + @Test + void anAnswerThatCannotBeRecordedIsReportedWithoutItsBody() throws Exception { + doThrow(new IllegalStateException("the database is unavailable")).when(store).recordResponse(eq(KEY), eq(200), + eq("{\"amount\":1.50}")); + + runWith("application/json", "{\"amount\":1.50}"); + + assertFalse(logged().contains("{\"amount\":1.50}"), "The body must not reach the log, even when recording it failed."); + assertTrue(logged().contains(KEY) && logged().contains("application/json"), + "A record that could not be written leaves the key unanswerable, which has to be loud - but it is the " + + "failure that is logged, not the answer."); + } + + @Test + void aJsonAnswerIsRecordedRatherThanLogged() throws Exception { + runWith("application/json", "{\"amount\":1.50}"); + + verify(store).recordResponse(KEY, 200, "{\"amount\":1.50}"); + + assertTrue(logged().isEmpty(), "Nothing is lost on the ordinary path, so nothing is logged about it."); + } + + private MockHttpServletResponse runWith(String contentType, String body) throws Exception { + var request = new MockHttpServletRequest("POST", "/commands"); + + request.addHeader(IdempotencyCommandProperties.builder().build().getKeyHeaderName(), KEY); + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, KEY); + + var response = new MockHttpServletResponse(); + var chain = new MockFilterChain() { + + @Override + public void doFilter(jakarta.servlet.ServletRequest req, jakarta.servlet.ServletResponse res) throws java.io.IOException { + res.setContentType(contentType); + res.getWriter().write(body); + } + }; + + filter.doFilter(request, response, chain); + + return response; + } + + private String logged() { + return captured.list.stream().filter(event -> event.getLevel().isGreaterOrEqual(Level.WARN)).map(ILoggingEvent::getFormattedMessage) + .reduce("", String::concat); + } +} diff --git a/fineract-command-idempotency/src/test/resources/application-test.properties b/fineract-command-idempotency/src/test/resources/application-test.properties new file mode 100644 index 00000000000..d35f0d3bb32 --- /dev/null +++ b/fineract-command-idempotency/src/test/resources/application-test.properties @@ -0,0 +1,45 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +fineract.command.enabled=true +fineract.command.hook-servlet-headers-enabled=true +fineract.command.hook-timestamp-enabled=true +fineract.command.hook-username-enabled=true + +fineract.command.jdbc.enabled=true +fineract.command.jdbc.file-dead-letter-queue-enabled=false +fineract.command.jdbc.file-dead-letter-queue-path=./build/fineract/dlq + +fineract.command.audit.enabled=true +fineract.command.audit.hook-pre-enabled=true +fineract.command.audit.hook-post-enabled=true +fineract.command.audit.hook-error-enabled=true + +fineract.command.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true + +spring.liquibase.enabled=true +spring.liquibase.drop-first=true +spring.liquibase.default-schema=public +spring.liquibase.change-log=classpath:/db/changelog/tenant/module/command/module-changelog-master.xml + +# the sample API renders errors through a MessageSource, same as the real application does +spring.messages.basename=org/apache/fineract/messages diff --git a/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties b/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties new file mode 100644 index 00000000000..eb14d22f2db --- /dev/null +++ b/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties @@ -0,0 +1,71 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# common +org.apache.fineract.common.validation.error=Validation Error +org.apache.fineract.common.validation.AssertFalse.message=must be false +org.apache.fineract.common.validation.AssertTrue.message=must be true +org.apache.fineract.common.validation.DecimalMax.message=must be less than ${inclusive == true ? 'or equal to ' : ''}{value} +org.apache.fineract.common.validation.DecimalMin.message=must be greater than ${inclusive == true ? 'or equal to ' : ''}{value} +org.apache.fineract.common.validation.Digits.message=numeric value out of bounds (<{integer} digits>.<{fraction} digits> expected) +org.apache.fineract.common.validation.Email.message=must be a well-formed email address +org.apache.fineract.common.validation.Future.message=must be a future date +org.apache.fineract.common.validation.FutureOrPresent.message=must be a date in the present or in the future +org.apache.fineract.common.validation.Max.message=must be less than or equal to {value} +org.apache.fineract.common.validation.Min.message=must be greater than or equal to {value} +org.apache.fineract.common.validation.Negative.message=must be less than 0 +org.apache.fineract.common.validation.NegativeOrZero.message=must be less than or equal to 0 +org.apache.fineract.common.validation.NotBlank.message=must not be blank +org.apache.fineract.common.validation.NotEmpty.message=must not be empty +org.apache.fineract.common.validation.NotNull.message=must not be null +org.apache.fineract.common.validation.Null.message=must be null +org.apache.fineract.common.validation.Past.message=must be a past date +org.apache.fineract.common.validation.PastOrPresent.message=must be a date in the past or in the present +org.apache.fineract.common.validation.Pattern.message=must match "{regexp}" +org.apache.fineract.common.validation.Positive.message=must be greater than 0 +org.apache.fineract.common.validation.PositiveOrZero.message=must be greater than or equal to 0 +org.apache.fineract.common.validation.Size.message=size must be between {min} and {max} +org.apache.fineract.common.validation.CreditCardNumber.message=invalid credit card number +org.apache.fineract.common.validation.Currency.message=invalid currency (must be one of {value}) +org.apache.fineract.common.validation.EAN.message=invalid {type} barcode +org.apache.fineract.common.validation.ISBN.message=invalid ISBN +org.apache.fineract.common.validation.Length.message=length must be between {min} and {max} +org.apache.fineract.common.validation.CodePointLength.message=length must be between {min} and {max} +org.apache.fineract.common.validation.LuhnCheck.message=the check digit for ${validatedValue} is invalid, Luhn Modulo 10 checksum failed +org.apache.fineract.common.validation.Mod10Check.message=the check digit for ${validatedValue} is invalid, Modulo 10 checksum failed +org.apache.fineract.common.validation.Mod11Check.message=the check digit for ${validatedValue} is invalid, Modulo 11 checksum failed +org.apache.fineract.common.validation.ModCheck.message=the check digit for ${validatedValue} is invalid, {modType} checksum failed +org.apache.fineract.common.validation.Normalized.message=must be normalized +org.apache.fineract.common.validation.ParametersScriptAssert.message=script expression "{script}" didn't evaluate to true +org.apache.fineract.common.validation.Range.message=must be between {min} and {max} +org.apache.fineract.common.validation.ScriptAssert.message=script expression "{script}" didn't evaluate to true +org.apache.fineract.common.validation.UniqueElements.message=must only contain unique elements +org.apache.fineract.common.validation.URL.message=must be a valid URL +org.apache.fineract.common.validation.UUID.message=must be a valid UUID +org.apache.fineract.common.validation.br.CNPJ.message=invalid Brazilian corporate taxpayer registry number (CNPJ) +org.apache.fineract.common.validation.br.CPF.message=invalid Brazilian individual taxpayer registry number (CPF) +org.apache.fineract.common.validation.br.TituloEleitoral.message=invalid Brazilian Voter ID card number +org.apache.fineract.common.validation.pl.REGON.message=invalid Polish Taxpayer Identification Number (REGON) +org.apache.fineract.common.validation.pl.NIP.message=invalid VAT Identification Number (NIP) +org.apache.fineract.common.validation.pl.PESEL.message=invalid Polish National Identification Number (PESEL) +org.apache.fineract.common.validation.ru.INN.message=invalid Russian taxpayer identification number (INN) +org.apache.fineract.common.validation.time.DurationMax.message=must be shorter than${inclusive == true ? ' or equal to' : ''}${days == 0 ? '' : days == 1 ? ' 1 day' : ' ' += days += ' days'}${hours == 0 ? '' : hours == 1 ? ' 1 hour' : ' ' += hours += ' hours'}${minutes == 0 ? '' : minutes == 1 ? ' 1 minute' : ' ' += minutes += ' minutes'}${seconds == 0 ? '' : seconds == 1 ? ' 1 second' : ' ' += seconds += ' seconds'}${millis == 0 ? '' : millis == 1 ? ' 1 milli' : ' ' += millis += ' millis'}${nanos == 0 ? '' : nanos == 1 ? ' 1 nano' : ' ' += nanos += ' nanos'} +org.apache.fineract.common.validation.time.DurationMin.message=must be longer than${inclusive == true ? ' or equal to' : ''}${days == 0 ? '' : days == 1 ? ' 1 day' : ' ' += days += ' days'}${hours == 0 ? '' : hours == 1 ? ' 1 hour' : ' ' += hours += ' hours'}${minutes == 0 ? '' : minutes == 1 ? ' 1 minute' : ' ' += minutes += ' minutes'}${seconds == 0 ? '' : seconds == 1 ? ' 1 second' : ' ' += seconds += ' seconds'}${millis == 0 ? '' : millis == 1 ? ' 1 milli' : ' ' += millis += ' millis'}${nanos == 0 ? '' : nanos == 1 ? ' 1 nano' : ' ' += nanos += ' nanos'} +# dummy +org.apache.fineract.dummy.request.content.not-empty=Dummy request content must have a value diff --git a/fineract-command-jdbc/dependencies.gradle b/fineract-command-jdbc/dependencies.gradle index 6027c1f7788..838ef806425 100644 --- a/fineract-command-jdbc/dependencies.gradle +++ b/fineract-command-jdbc/dependencies.gradle @@ -43,6 +43,10 @@ dependencies { annotationProcessor 'org.mapstruct:mapstruct-processor' testImplementation 'org.springframework.boot:spring-boot-liquibase' + // @Retry is an AspectJ aspect, so without this the annotations read as present and do nothing; the application + // that uses this module brings it, and the retry tests need it here to exercise the real behaviour + testImplementation 'org.aspectj:aspectjweaver' + testImplementation(project(path: ':fineract-command-test')) testImplementation ('org.springframework.boot:spring-boot-starter-test') { exclude group: 'com.jayway.jsonpath', module: 'json-path' diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java index ef880f13c2d..3bd2f575833 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java @@ -21,6 +21,8 @@ import static java.nio.charset.StandardCharsets.UTF_8; import static java.util.Objects.isNull; import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.CommandState.UNKNOWN; import io.github.resilience4j.retry.annotation.Retry; import java.io.IOException; @@ -28,21 +30,24 @@ import java.util.Optional; import java.util.UUID; import lombok.RequiredArgsConstructor; -import lombok.SneakyThrows; import lombok.extern.slf4j.Slf4j; import org.apache.commons.io.FileUtils; import org.apache.fineract.command.core.Command; import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandReplay; import org.apache.fineract.command.core.CommandStore; import org.apache.fineract.command.jdbc.JdbcCommandProperties; -import org.apache.fineract.command.jdbc.store.domain.CommandEntity; import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; import org.apache.fineract.command.jdbc.store.mapping.JdbcCommandMapper; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.context.event.ApplicationStartedEvent; import org.springframework.context.event.EventListener; +import org.springframework.dao.DuplicateKeyException; import org.springframework.stereotype.Component; +import tools.jackson.databind.JsonNode; import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.node.ObjectNode; @Slf4j @RequiredArgsConstructor @@ -51,6 +56,7 @@ public class JdbcCommandStore implements CommandStore { private final JdbcCommandMapper mapper; + private final JsonCommandMapper jsonMapper; private final JdbcCommandRepository repository; private final ObjectMapper objectMapper; private final JdbcCommandProperties properties; @@ -71,16 +77,77 @@ public boolean existsByKey(String key) { } @Override - public boolean checkRequestInstanceByKey(String key, Class clazz) { - return repository.findOneByIdempotencyKey(key).map(CommandEntity::getResponse) - .map(json -> clazz.getCanonicalName().equals(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asText())).orElse(false); + public CommandReplay getReplayByKey(String key) { + return repository.findOneByIdempotencyKey(key).map( + entity -> new CommandReplay(entity.getState(), entity.getResponseStatusCode(), replayResponse(key, entity.getResponse()))) + .orElseGet(() -> new CommandReplay(UNKNOWN, null, null)); + } + + /** + * What a repeat is answered with. Normally the command's own result, rehydrated into the object it was, so that the + * web layer renders the replay with the very serializer that rendered the original answer - the two are identical + * because they are the same object rendered the same way, not because two serializers were made to agree. + * + *

+ * A command that produced no result of its own leaves only what was captured as it went out, and that is replayed + * as the text it was stored as. Re-rendering it would change the bytes: a decimal written as 1.50 comes back 1.5. + */ + private Object replayResponse(String key, JsonNode stored) { + if (isNull(stored)) { + return null; + } + + if (stored instanceof ObjectNode object && object.has(COMMAND_JSON_CLASS_ATTRIBUTE)) { + return jsonMapper.map(stored); + } + + return repository.findResponseTextByIdempotencyKey(key).orElse(null); + } + + @Override + @Retry(name = "commandStore") + public void recordResponse(String key, int statusCode, String body) { + var updated = repository.updateResponse(key, statusCode, body); + + log.debug("Recorded response {} for idempotency key {} ({} row(s))", statusCode, key, updated); + } + + @Override + @Retry(name = "commandStore") + public boolean claim(Command command) { + final var commandEntity = mapper.map(command); + + commandEntity.setState(UNDER_PROCESSING); + + try { + repository.save(commandEntity); + command.setCommandId(commandEntity.getId()); + + log.debug("Claimed idempotency key {} with command id {}", command.getIdempotencyKey(), commandEntity.getId()); + + return true; + } catch (RuntimeException e) { + if (isDuplicateKey(e)) { + log.debug("Idempotency key {} is already claimed", command.getIdempotencyKey()); + + return false; + } + + throw e; + } } @Override - @SuppressWarnings("unchecked") - public T getResponseByKey(String key) { - return (T) repository.findOneByIdempotencyKey(key).map(CommandEntity::getResponse) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public boolean matchesStoredRequest(String key, Object payload) { + if (isNull(payload)) { + return false; + } + + // compared as text rather than as parsed nodes: the stored text was written by this same mapper, so an + // identical request produces identical text, while parsing would round a decimal through a double and make + // two amounts that differ only in their last digits look like the same request + return repository.findRequestTextByIdempotencyKey(key) + .map(stored -> stored.equals(objectMapper.writeValueAsString(jsonMapper.map(payload)))).orElse(false); } @Override @@ -117,6 +184,14 @@ void fallback(CommandContext ctx, Throwable t) throws Exception { final var command = ctx.getCommand(); final var state = ctx.getState(); + // a duplicate key is never a "store it later" problem: swallowing it would let a second request carry on as if + // its command had been recorded, and execute again + if (isDuplicateKey(t)) { + log.error("Command store rejected a duplicate idempotency key {}", command.getIdempotencyKey(), t); + + throw t instanceof Exception e ? e : new IllegalStateException(t); + } + log.warn("Command store fallback idempotencyKey={}, state={}, payloadType={}, deadLetterQueueEnabled={}", command.getIdempotencyKey(), state, payloadType(command), properties.getFileDeadLetterQueueEnabled(), t); if (Boolean.TRUE.equals(properties.getFileDeadLetterQueueEnabled())) { @@ -134,9 +209,15 @@ void onStartup() { } } - @SneakyThrows - private Class forName(String clazz) { - return Class.forName(clazz); + // Spring Data JDBC wraps the translated exception in a DbActionExecutionException, so the whole chain is inspected + private static boolean isDuplicateKey(Throwable t) { + for (var current = t; current != null; current = current.getCause()) { + if (current instanceof DuplicateKeyException) { + return true; + } + } + + return false; } private void write(Command command) throws IOException { diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java index c25c79baa74..8768134325a 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java @@ -26,6 +26,7 @@ import lombok.ToString; import lombok.experimental.FieldNameConstants; import org.springframework.data.annotation.Id; +import org.springframework.data.annotation.ReadOnlyProperty; import org.springframework.data.relational.core.mapping.Column; import org.springframework.data.relational.core.mapping.Table; import tools.jackson.databind.JsonNode; @@ -74,6 +75,14 @@ public class CommandEntity implements Serializable { @Column("idempotency_key") private String idempotencyKey; + /** + * The HTTP status the original request was answered with, so a repeat of it can be answered identically. Written + * only by the store's targeted update; a full-row save must not reset it, hence read-only here. + */ + @ReadOnlyProperty + @Column("response_status_code") + private Integer responseStatusCode; + @Column("state") private org.apache.fineract.command.core.CommandState state; diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java index dcec7c4816a..365c5b8cde7 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java @@ -19,7 +19,10 @@ package org.apache.fineract.command.jdbc.store.domain; import java.util.Optional; +import org.springframework.data.jdbc.repository.query.Modifying; +import org.springframework.data.jdbc.repository.query.Query; import org.springframework.data.repository.ListCrudRepository; +import org.springframework.data.repository.query.Param; import org.springframework.data.repository.query.QueryByExampleExecutor; public interface JdbcCommandRepository extends ListCrudRepository, QueryByExampleExecutor { @@ -27,4 +30,39 @@ public interface JdbcCommandRepository extends ListCrudRepository findOneByIdempotencyKey(String idempotencyKey); boolean existsByIdempotencyKey(String idempotencyKey); + + /** + * Records what the original request was answered with, but only for a command that stored no result of its own. + * + *

+ * A command that did store a result needs none of this: its repeat is answered by handing that result back through + * the dispatcher, so the resource and the web layer produce the status and the bytes exactly as they produced them + * the first time. Recording anything for it would be dead weight, which is why the update excludes it rather than + * overwriting nothing. What is left is the case with no result to hand back - a failure, whose answer is rendered + * from an exception, and an answer that is not JSON - and there the status has to be recorded too, because a replay + * of it is thrown rather than returned and nothing else can tell the mapper what status to use. + */ + @Modifying + @Query(""" + UPDATE m_command + SET response_status_code = :statusCode, response = :body + WHERE idempotency_key = :idempotencyKey AND response IS NULL + """) + int updateResponse(@Param("idempotencyKey") String idempotencyKey, @Param("statusCode") int statusCode, @Param("body") String body); + + /** + * Reads the stored response as the exact text it was stored as, for the fallback case where there is no result + * object to rehydrate. Going through the mapped JSON node would re-render it, and re-rendering changes the bytes: a + * decimal written as 1.50 comes back as 1.5. + */ + @Query("SELECT response FROM m_command WHERE idempotency_key = :idempotencyKey") + Optional findResponseTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey); + + /** + * Reads the stored request as the exact text it was stored as, for comparing a retry against it. Comparing parsed + * nodes instead would collapse a decimal to a double, so two amounts differing beyond a double's precision would + * compare equal and the wrong answer would be replayed. + */ + @Query("SELECT request FROM m_command WHERE idempotency_key = :idempotencyKey") + Optional findRequestTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey); } diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java index faaa5369de8..1e3290430ce 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java @@ -46,10 +46,10 @@ public T map(JsonNode source) { try { return (T) mapper.convertValue(source, Class.forName(canonicalName)); } catch (Exception e) { - log.error("Error while mapping json node", e); + // returning null here would answer a repeated request with an empty body rather than with the answer it + // was given the first time, and say so only in the log + throw new IllegalStateException("Cannot rehydrate a stored command result of type " + canonicalName, e); } - - return null; } public JsonNode map(Object source) { diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml index 5579401453b..a01e922530d 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml @@ -25,5 +25,6 @@ + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml index 29376532cba..e07e9a475c8 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml @@ -23,21 +23,47 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.1.xsd"> - + + Make idempotency keys unique without losing any audit history. Where several rows share a key, + the earliest one keeps it and the surplus rows get their row ID appended, so the original key + stays readable and the record survives. No command record is deleted. + + Two details are deliberate: the rows are selected by ID and wrapped in a derived table because + MySQL cannot reference the UPDATE target table directly in a subquery (error 1093), and the + existing key is truncated before the suffix is appended so the result still fits varchar(255). + + + - idempotency_key IN ( - SELECT c1.idempotency_key - FROM m_command c1 - INNER JOIN m_command c2 - ON c1.idempotency_key = c2.idempotency_key - AND c1.id > c2.id + id IN ( + SELECT dup.id + FROM ( + SELECT id, ROW_NUMBER() OVER (PARTITION BY idempotency_key ORDER BY id) AS dup_rank + FROM m_command + WHERE idempotency_key IS NOT NULL + ) dup + WHERE dup.dup_rank > 1 ) - - + + + constraintName="m_command_idempotency_key_unique"/> + + + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml new file mode 100644 index 00000000000..9af3d73d007 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml @@ -0,0 +1,37 @@ + + + + + + A repeated request is normally answered from the command's own result, which the web layer renders with + the status it derived the first time, so nothing about the original response has to be recorded for it. + This column covers the case that leaves no result behind - a failure, whose answer comes from an exception + mapper, and an answer that is not JSON. There the recorded answer is thrown rather than returned, and + nothing else could say what status to use. + + + + + + diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java new file mode 100644 index 00000000000..917df2f7f68 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java @@ -0,0 +1,174 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.sql.Statement; +import liquibase.Contexts; +import liquibase.LabelExpression; +import liquibase.Liquibase; +import liquibase.database.DatabaseFactory; +import liquibase.database.jvm.JdbcConnection; +import liquibase.resource.ClassLoaderResourceAccessor; +import lombok.extern.slf4j.Slf4j; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.testcontainers.DockerClientFactory; +import org.testcontainers.containers.JdbcDatabaseContainer; +import org.testcontainers.containers.MariaDBContainer; +import org.testcontainers.containers.MySQLContainer; +import org.testcontainers.containers.PostgreSQLContainer; +import org.testcontainers.containers.wait.strategy.Wait; +import org.testcontainers.utility.DockerImageName; + +/** + * Verifies the idempotency key migration against a database that already contains rows sharing a key, which is the + * state of any system that ran an earlier build. + *

+ * The migration must let the earliest row per key keep it, make the surplus rows unique without deleting them, leave + * rows without a key untouched, and run on every supported database - MySQL in particular rejects a subquery that + * references the UPDATE target table. + */ +@Slf4j +public class CommandIdempotencyKeyMigrationTest { + + /** + * Deliberately not under {@code db/changelog}: this is a test harness that seeds old rows and then runs the real + * parts, not a master changelog. The registration check treats every file under {@code db/changelog} that has an + * {@code } as a master, and would read this one as including the production parts a second time. + */ + private static final String CHANGELOG = "liquibase-test/command-migration-test-changelog.xml"; + + @BeforeAll + static void requireDocker() { + assumeTrue(DockerClientFactory.instance().isDockerAvailable(), "Docker not available, skipping Testcontainers tests"); + } + + @Test + public void postgres() throws Exception { + try (var container = new PostgreSQLContainer<>(DockerImageName.parse("postgres:18.3"))) { + verify(container, "postgresql"); + } + } + + @Test + public void mysql() throws Exception { + try (var container = new MySQLContainer<>(DockerImageName.parse("mysql:8"))) { + verify(container, "mysql"); + } + } + + @Test + public void mariadb() throws Exception { + try (var container = new MariaDBContainer<>(DockerImageName.parse("mariadb:12.2")).withCommand("--innodb-snapshot-isolation=OFF") + .waitingFor(Wait.forListeningPort())) { + verify(container, "mysql"); + } + } + + private void verify(JdbcDatabaseContainer container, String context) throws Exception { + container.start(); + + migrate(container, context); + + try (var connection = connect(container)) { + assertEquals(6, count(connection, "1 = 1"), "The migration must not remove any command record."); + + assertEquals(1, count(connection, "idempotency_key = 'KEEP-1'"), "Only one row may keep a given idempotency key."); + assertEquals(1, count(connection, "idempotency_key = 'KEEP-1' AND id = 1 AND request = 'original'"), + "The earliest row must be the one that keeps the key."); + + // the surplus rows survive with a readable, traceable key rather than being deleted + assertEquals(1, count(connection, "idempotency_key = 'KEEP-1-duplicate-2' AND id = 2 AND request = 'surplus'"), + "A surplus row must survive with the original key plus its row id."); + assertEquals(1, count(connection, "idempotency_key = 'KEEP-1-duplicate-3' AND id = 3 AND request = 'surplus'"), + "Every surplus row must survive, each with its own key."); + + assertEquals(1, count(connection, "idempotency_key = 'KEEP-2' AND id = 4"), "A key with a single row must be left untouched."); + assertEquals(2, count(connection, "idempotency_key IS NULL"), "Rows without an idempotency key must be left untouched."); + + assertEquals(0, count(connection, "response_status_code IS NOT NULL"), "No status has been recorded for existing rows."); + + assertThrows(SQLException.class, () -> insert(connection, 100, "KEEP-1"), + "The unique constraint should reject a second row with the same idempotency key."); + + // several rows without a key stay legal under the unique constraint + insert(connection, 101, null); + assertEquals(3, count(connection, "idempotency_key IS NULL"), "The unique constraint must not apply to null keys."); + + assertThrows(SQLException.class, () -> insert(connection, 103, "KEEP-1-duplicate-2"), "A suffixed key must be unique as well."); + } + + rollbackUniqueConstraint(container, context); + + try (var connection = connect(container)) { + insert(connection, 102, "KEEP-1"); + assertEquals(2, count(connection, "idempotency_key = 'KEEP-1'"), "After rollback duplicate keys should be accepted again."); + } + } + + private static Connection connect(JdbcDatabaseContainer container) throws SQLException { + return DriverManager.getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword()); + } + + // note: Liquibase closes the connection it was given, so it always gets one of its own + private void migrate(JdbcDatabaseContainer container, String context) throws Exception { + try (var connection = connect(container); var liquibase = liquibase(connection)) { + liquibase.update(new Contexts(context), new LabelExpression()); + } + } + + /** + * Reverts the unique constraint, which means also reverting the response-cache changeset stacked on top of it. Both + * databases apply the same number of changesets from that point on. + */ + private void rollbackUniqueConstraint(JdbcDatabaseContainer container, String context) throws Exception { + try (var connection = connect(container); var liquibase = liquibase(connection)) { + liquibase.rollback(2, new Contexts(context), new LabelExpression()); + } + } + + private static Liquibase liquibase(Connection connection) throws Exception { + return new Liquibase(CHANGELOG, new ClassLoaderResourceAccessor(), + DatabaseFactory.getInstance().findCorrectDatabaseImplementation(new JdbcConnection(connection))); + } + + private static int count(Connection connection, String where) throws SQLException { + try (Statement statement = connection.createStatement(); + var resultSet = statement.executeQuery("SELECT COUNT(*) FROM m_command WHERE " + where)) { + resultSet.next(); + + return resultSet.getInt(1); + } + } + + private static void insert(Connection connection, long id, String key) throws SQLException { + try (var statement = connection.prepareStatement("INSERT INTO m_command (id, idempotency_key, state) VALUES (?, ?, 'PROCESSED')")) { + statement.setLong(1, id); + statement.setString(2, key); + statement.executeUpdate(); + } + } +} diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java new file mode 100644 index 00000000000..56508afaf38 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java @@ -0,0 +1,122 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyInt; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +import io.github.resilience4j.springboot.retry.autoconfigure.RetryAutoConfiguration; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.jdbc.store.JdbcCommandStore; +import org.apache.fineract.command.jdbc.store.domain.CommandEntity; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.jdbc.store.mapping.JdbcCommandMapper; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.dao.ConcurrencyFailureException; + +/** + * Checks that every write to the command row is actually retried, rather than merely annotated. + * + *

+ * The annotation on its own proves nothing: a method that catches its own exception never gives the retry anything to + * react to, so the retry reads as present and does nothing. These drive each write through a repository that fails with + * the contention the policy is configured for, and count how many times it was asked. + */ +class JdbcCommandStoreRetryTest { + + private static final int MAX_ATTEMPTS = 3; + + private final JdbcCommandRepository repository = mock(JdbcCommandRepository.class); + + private final JdbcCommandMapper mapper = mock(JdbcCommandMapper.class); + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(AopAutoConfiguration.class, RetryAutoConfiguration.class)) + .withUserConfiguration(StoreConfiguration.class).withBean(JdbcCommandRepository.class, () -> repository) + .withBean(JdbcCommandMapper.class, () -> mapper) + .withPropertyValues("resilience4j.retry.instances.commandStore.max-attempts=" + MAX_ATTEMPTS, + "resilience4j.retry.instances.commandStore.wait-duration=1ms", + "resilience4j.retry.instances.commandStore.retryExceptions=org.springframework.dao.ConcurrencyFailureException"); + + @Test + void claimingAKeyIsRetriedWhenItLosesToContention() { + when(mapper.map(any(Command.class))).thenReturn(new CommandEntity()); + when(repository.save(any())).thenThrow(new ConcurrencyFailureException("contention")); + + contextRunner.run(context -> { + var store = context.getBean(CommandStore.class); + + assertThat(catchFailure(() -> store.claim(command()))).isInstanceOf(ConcurrencyFailureException.class); + verify(repository, times(MAX_ATTEMPTS)).save(any(CommandEntity.class)); + }); + } + + @Test + void recordingTheAnswerIsRetried() { + when(repository.updateResponse(anyString(), anyInt(), any())).thenThrow(new ConcurrencyFailureException("contention")); + + contextRunner.run(context -> { + var store = context.getBean(CommandStore.class); + + assertThat(catchFailure(() -> store.recordResponse("a-key", 400, "{}"))).isInstanceOf(ConcurrencyFailureException.class); + verify(repository, times(MAX_ATTEMPTS)).updateResponse(anyString(), anyInt(), any()); + }); + } + + private static Throwable catchFailure(Runnable runnable) { + try { + runnable.run(); + + return null; + } catch (Throwable t) { + return t; + } + } + + private static Command command() { + var command = new Command<>(); + + command.setIdempotencyKey("a-key"); + + return command; + } + + @Configuration + static class StoreConfiguration { + + @Bean + CommandStore commandStore(JdbcCommandMapper mapper, JdbcCommandRepository repository) { + return new JdbcCommandStore(mapper, mock(JsonCommandMapper.class), repository, mock(tools.jackson.databind.ObjectMapper.class), + null); + } + } +} diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java new file mode 100644 index 00000000000..9dd0e0cc76f --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -0,0 +1,325 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.CommandState.UNKNOWN; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.math.BigDecimal; +import java.time.Instant; +import java.time.LocalDate; +import java.time.OffsetDateTime; +import java.util.Locale; +import java.util.UUID; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.stream.IntStream; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.apache.fineract.command.test.sample.data.DummyResponse; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ContextConfiguration; + +@Slf4j +@SpringBootTest +@ContextConfiguration(classes = TestConfiguration.class) +public class JdbcCommandStoreTest extends CommandBaseTest { + + @Autowired + protected CommandStore store; + + @Autowired + protected JdbcCommandRepository repository; + + @Test + public void aStoredResponseIsReplayedAsTheObjectTheCommandProduced() { + var key = UUID.randomUUID().toString(); + + store.store(processed(key, "hello")); + + var replayed = store.getReplayByKey(key).response(); + + assertNotNull(replayed, "A processed command should replay its stored response."); + assertInstanceOf(DummyResponse.class, replayed, "The response is rehydrated to its own type, not handed back as text."); + assertEquals("HELLO", ((DummyResponse) replayed).getContent(), "The replay must carry the original response content."); + } + + @Test + public void onlyAnIdenticalRequestMatchesTheStoredOne() { + var key = UUID.randomUUID().toString(); + + store.store(processed(key, "hello")); + + assertTrue(store.matchesStoredRequest(key, DummyRequest.builder().content("hello").build()), + "The same request must match the stored one."); + assertFalse(store.matchesStoredRequest(key, DummyRequest.builder().content("goodbye").build()), + "A different request of the same type must not match; it would replay an unrelated response."); + assertFalse(store.matchesStoredRequest(key, DummyResponse.builder().content("hello").build()), + "A different request type must not match."); + assertFalse(store.matchesStoredRequest(key, null), "A null payload must not match."); + assertFalse(store.matchesStoredRequest(UUID.randomUUID().toString(), DummyRequest.builder().content("hello").build()), + "An unknown idempotency key must not match anything."); + } + + @Test + public void anIdenticalRetryIsRecognisedWhateverTypesTheRequestCarries() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + command.setPayload(fullyPopulated()); + + store.claim(command); + + assertTrue(store.matchesStoredRequest(key, fullyPopulated()), + "An identical retry must be recognised whatever field types the request carries."); + } + + @Test + public void aChangeToAnyFieldMakesItADifferentRequest() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + command.setPayload(fullyPopulated()); + + store.claim(command); + + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().content("other").build()), + "A different string must not be replayed."); + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().referenceId(8L).build()), + "A different id must not be replayed."); + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().count(2).build()), + "A different whole number must not be replayed."); + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().flag(false).build()), + "A different flag must not be replayed."); + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().amount(new BigDecimal("150.00")).build()), + "A different amount must not be replayed."); + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().businessDate(LocalDate.of(2026, 10, 6)).build()), + "A different date must not be replayed."); + // one nanosecond apart, which also shows whether sub-second precision survives being stored + assertFalse( + store.matchesStoredRequest(key, + fullyPopulated().toBuilder().timestamp(OffsetDateTime.parse("2026-10-05T11:22:33.123456788Z")).build()), + "A different timestamp must not be replayed."); + + // the case a comparison through a double would miss: a difference past the 17th significant digit + assertFalse( + store.matchesStoredRequest(key, + fullyPopulated().toBuilder().preciseAmount(new BigDecimal("12345678901234567890.12345678902")).build()), + "Two amounts that differ beyond a double's precision are different requests."); + } + + @Test + public void aDecimalKeepsItsScaleWhenComparedAgainstAStoredRequest() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + command.setPayload(fullyPopulated()); + + store.claim(command); + + // 1.50 and 1.5 are the same number but not the same request body, and the conservative answer is the safe one + assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().amount(new BigDecimal("100.0")).build()), + "An amount written with a different scale must not be taken for the stored one."); + } + + @Test + public void claimSucceedsOnceAndSetsTheCommandId() { + var key = UUID.randomUUID().toString(); + var first = command(key, "hello"); + + assertTrue(store.claim(first), "The first claim of an idempotency key should succeed."); + assertNotNull(first.getCommandId(), "A successful claim should assign the command id."); + assertTrue(store.existsByKey(key), "A claimed key should be visible to other requests immediately."); + + assertFalse(store.claim(command(key, "hello")), "A second claim of the same idempotency key should fail."); + } + + @Test + public void commandsWithoutAKeyNeverConflict() { + assertTrue(store.claim(command(null, "hello")), "A command without an idempotency key should always be claimable."); + assertTrue(store.claim(command(null, "hello")), "Commands without an idempotency key should not conflict with each other."); + } + + @Test + public void onlyOneConcurrentClaimOfTheSameKeyWins() throws Exception { + var threads = 8; + var key = UUID.randomUUID().toString(); + var startLine = new CountDownLatch(1); + var winners = new AtomicInteger(); + + try (var executor = Executors.newFixedThreadPool(threads)) { + var attempts = IntStream.range(0, threads).mapToObj(i -> executor.submit(() -> { + startLine.await(); + + if (store.claim(command(key, "hello"))) { + winners.incrementAndGet(); + } + + return null; + })).toList(); + + startLine.countDown(); + + for (var attempt : attempts) { + attempt.get(30, TimeUnit.SECONDS); + } + } + + assertEquals(1, winners.get(), "Exactly one concurrent request may claim a key; the rest must be told to stand down."); + assertEquals(1, repository.findAll().stream().filter(e -> key.equals(e.getIdempotencyKey())).count(), + "Only one command row may exist per idempotency key."); + } + + @Test + public void theStateOfAKeyTellsAnInFlightCommandFromAFinishedOne() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + assertEquals(UNKNOWN, store.getReplayByKey(key).state(), "An unclaimed key has no state."); + + store.claim(command); + + var inFlight = store.getReplayByKey(key); + assertEquals(UNDER_PROCESSING, inFlight.state(), "A claimed key should report the command as in flight."); + assertNull(inFlight.statusCode(), "An in-flight command has not been answered yet."); + assertNull(inFlight.response(), "An in-flight command has nothing to replay."); + + store.store(CommandContext.builder().command(command) + .response(DummyResponse.builder().content("HELLO").build()).state(PROCESSED).build()); + store.recordResponse(key, 201, null); + + var processed = store.getReplayByKey(key); + assertEquals(PROCESSED, processed.state(), "A completed command should report as processed."); + assertEquals("HELLO", ((DummyResponse) processed.response()).getContent(), + "The result the original command produced must be replayable."); + assertNull(processed.statusCode(), "A command that stored a result needs no status: its repeat is answered by " + + "handing that result back, and the web layer derives the status from it as it did the first time."); + } + + @Test + public void aFailedCommandReportsAsFailedRatherThanAsMissing() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + store.claim(command); + store.store(CommandContext.builder().command(command).state(ERROR).build()); + // a failed command produces no result of its own, so the error document the client got is what fills the gap + store.recordResponse(key, 400, "{\"error\":\"bad request\"}"); + + var failed = store.getReplayByKey(key); + assertEquals(ERROR, failed.state(), "A failed command should report as failed."); + assertEquals(400, failed.statusCode(), "The status the failure was answered with must be replayable."); + assertEquals("{\"error\":\"bad request\"}", failed.response(), + "With no result object to rehydrate, the failure replays as the text the client was sent."); + } + + @Test + public void nothingIsCapturedForACommandThatStoredItsOwnResult() { + var key = UUID.randomUUID().toString(); + + store.store(processed(key, "hello")); + + store.recordResponse(key, 200, "{\"content\":\"CAPTURED\"}"); + + var replay = store.getReplayByKey(key); + + assertInstanceOf(DummyResponse.class, replay.response(), "A repeat is answered from the command's own result."); + assertEquals("HELLO", ((DummyResponse) replay.response()).getContent()); + assertNull(replay.statusCode(), "Neither the captured answer nor its status is recorded over a stored result; " + + "the result is handed back through the dispatcher and the web layer answers from it."); + } + + @Test + public void aCapturedAnswerIsReplayedByteForByteWhenThereIsNoResultToRehydrate() { + var key = UUID.randomUUID().toString(); + + // every shape that changes when a stored answer is parsed and re-rendered rather than kept as it was written: + // trailing zeros on a decimal, a value past a double's precision, exponents, dates, times and nulls + var answer = """ + {"amount":1.50,"rate":0.0100,"precise":12345678901234567890.12345678901,\ + "exponent":1.0E10,"whole":7,"big":9223372036854775807,"text":"x","unicode":"é",\ + "date":"2026-10-05","timestamp":"2026-10-05T11:22:33.123456789Z","nothing":null,\ + "nested":{"inner":0.100},"list":[1.10,2.20]}"""; + + store.claim(command(key, "hello")); + store.recordResponse(key, 200, answer); + + assertEquals(answer, store.getReplayByKey(key).response(), + "A captured answer must replay exactly as the client was sent it, byte for byte."); + } + + @Test + public void storingTheCommandDoesNotResetTheRecordedStatus() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + store.claim(command); + store.recordResponse(key, 400, "{\"error\":\"bad request\"}"); + + // the audit hooks rebuild the row from the command, which has no notion of the status the client was sent + store.store(CommandContext.builder().command(command).state(ERROR).build()); + + assertEquals(400, store.getReplayByKey(key).statusCode(), "A full-row save must not wipe the recorded status."); + } + + private static CommandContext processed(String key, String content) { + return CommandContext.builder().command(command(key, content)) + .response(DummyResponse.builder().content(content.toUpperCase(Locale.ROOT)).build()).state(PROCESSED).build(); + } + + /** Every field type a request realistically carries, so a comparison cannot quietly ignore one of them. */ + private static DummyRequest fullyPopulated() { + return DummyRequest.builder().content("hello").referenceId(7L).count(1).flag(true).amount(new BigDecimal("100.00")) + .preciseAmount(new BigDecimal("12345678901234567890.12345678901")).businessDate(LocalDate.of(2026, 10, 5)) + .timestamp(OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z")).build(); + } + + private static DummyCommand command(String key, String content) { + var now = Instant.now(); + var command = new DummyCommand(); + + command.setPayload(DummyRequest.builder().content(content).build()); + command.setIdempotencyKey(key); + command.setIpAddress("127.0.0.1"); + command.setCreatedAt(now); + command.setUpdatedAt(now); + command.setExecutedAt(now); + command.setInitiatedByUsername("abc"); + command.setExecutedByUsername("abc"); + + return command; + } +} diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/RetryPolicyTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/RetryPolicyTest.java new file mode 100644 index 00000000000..3ed900318d2 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/RetryPolicyTest.java @@ -0,0 +1,90 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.assertj.core.api.Assertions.assertThat; + +import io.github.resilience4j.retry.RetryRegistry; +import io.github.resilience4j.springboot.retry.autoconfigure.RetryAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.dao.CannotAcquireLockException; +import org.springframework.dao.DataIntegrityViolationException; +import org.springframework.dao.DeadlockLoserDataAccessException; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.dao.QueryTimeoutException; +import org.springframework.dao.RecoverableDataAccessException; +import org.springframework.dao.TransientDataAccessResourceException; + +/** + * Pins which failures are worth another attempt, and proves the policy reaches an instance that does not state one. + * + *

+ * The distinction is whether the same call could succeed if it ran again. A deadlock, a lock timeout, a serialisation + * failure, a connection dropped mid-flight: all of those are about when the call happened rather than what it asked + * for, and a second attempt is the right response. A unique constraint is the opposite - the row is there, and it will + * still be there on the third attempt - so retrying only delays the answer and holds a connection while it does. + * + *

+ * The widened list is set on the command store alone. The jobs that post interest and run close-of-business keep the + * narrower one they already had, because a connection lost during commit leaves the outcome of that commit unknown, and + * retrying an interest posting there is how it gets posted twice. Writing the command row is safe to retry for the + * opposite reason: the idempotency key is unique, so a second attempt cannot write the row twice. + */ +class RetryPolicyTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(AopAutoConfiguration.class, RetryAutoConfiguration.class)).withPropertyValues( + // the same two lines the application sets for this instance, and for this instance only + "resilience4j.retry.instances.commandStore.retryExceptions=" + + "org.springframework.dao.TransientDataAccessException,org.springframework.dao.RecoverableDataAccessException", + "resilience4j.retry.instances.commandStore.ignoreExceptions=org.springframework.dao.DataIntegrityViolationException", + "resilience4j.retry.instances.commandStore.max-attempts=3"); + + @Test + void aFailureThatMightNotHappenAgainIsRetried() { + contextRunner.run(context -> { + var predicate = policyOf(context.getBean(RetryRegistry.class)); + + assertThat(predicate.test(new DeadlockLoserDataAccessException("deadlock", null))).as("a deadlock").isTrue(); + assertThat(predicate.test(new CannotAcquireLockException("lock timeout"))).as("a lock that could not be taken").isTrue(); + assertThat(predicate.test(new QueryTimeoutException("timeout"))).as("a query timeout").isTrue(); + assertThat(predicate.test(new TransientDataAccessResourceException("connection reset"))).as("a dropped connection").isTrue(); + assertThat(predicate.test(new RecoverableDataAccessException("connection lost"))).as("a recoverable failure").isTrue(); + }); + } + + @Test + void aFailureThatWouldHappenEveryTimeIsNotRetried() { + contextRunner.run(context -> { + var predicate = policyOf(context.getBean(RetryRegistry.class)); + + assertThat(predicate.test(new DuplicateKeyException("the key is already claimed"))) + .as("a unique constraint is a verdict, not a mishap").isFalse(); + assertThat(predicate.test(new DataIntegrityViolationException("a column will not take that value"))) + .as("the data is wrong and will still be wrong next time").isFalse(); + }); + } + + private static java.util.function.Predicate policyOf(RetryRegistry registry) { + return registry.retry("commandStore").getRetryConfig().getExceptionPredicate(); + } +} diff --git a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml new file mode 100644 index 00000000000..1309ed964fb --- /dev/null +++ b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java index babe94260d1..1b37de2469d 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java @@ -28,6 +28,9 @@ import lombok.extern.slf4j.Slf4j; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.command.DummyErrorCommand; +import org.apache.fineract.command.test.sample.data.DummyErrorRequest; +import org.apache.fineract.command.test.sample.data.DummyErrorResponse; import org.apache.fineract.command.test.sample.data.DummyRequest; import org.apache.fineract.command.test.sample.data.DummyResponse; import org.springframework.scheduling.annotation.Async; @@ -59,6 +62,18 @@ DummyResponse dummySync(@RequestHeader(value = COMMAND_HTTP_HEADER_TENANT_ID, re return result.get(); } + /** Always fails, so that the behaviour of a failing command can be exercised over HTTP. */ + @PostMapping("/error") + DummyErrorResponse dummyError(@RequestBody DummyErrorRequest request) { + var command = new DummyErrorCommand(); + + command.setPayload(request); + + Supplier result = pipeline.dispatch(command); + + return result.get(); + } + @Async @PostMapping("/async") CompletableFuture dummyAsync(@RequestHeader(value = COMMAND_HTTP_HEADER_TENANT_ID, required = false) String tenantId, diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java index df9d4ee2cba..8e0a2d0fd01 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java @@ -21,13 +21,16 @@ import jakarta.validation.constraints.NotEmpty; import java.io.Serial; import java.io.Serializable; +import java.math.BigDecimal; +import java.time.LocalDate; +import java.time.OffsetDateTime; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; import lombok.experimental.FieldNameConstants; -@Builder +@Builder(toBuilder = true) @Data @NoArgsConstructor @AllArgsConstructor @@ -39,4 +42,24 @@ public class DummyRequest implements Serializable { @NotEmpty(message = "{org.apache.fineract.dummy.content.not-empty}") private String content; + + /** + * Present so that tests exercise the field types real requests carry. Each of these serialises differently, and + * several of them change shape if a stored request or response is parsed and re-rendered rather than kept as it was + * written. + */ + private Long referenceId; + + private Integer count; + + private Boolean flag; + + private BigDecimal amount; + + /** Beyond what a double can represent, so a comparison that rounds through one would miss a real difference. */ + private BigDecimal preciseAmount; + + private LocalDate businessDate; + + private OffsetDateTime timestamp; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java new file mode 100644 index 00000000000..1840b5b391c --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +/** + * What is known about a command already stored under an idempotency key: enough to answer a repeated request exactly as + * the original one was answered, without executing anything. + * + * @param state + * the state the stored command is in + * @param statusCode + * the HTTP status the original request was answered with, {@code null} if it never completed + * @param response + * the response object the original command produced, rehydrated from the command store, {@code null} if it + * never completed. It is handed back to the web layer as an object rather than as text so that the same + * serializer that rendered the original answer renders the replay, which is what makes the two identical. + */ +public record CommandReplay(CommandState state, Integer statusCode, Object response) { +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java index 1922d1c6d38..8a6d831af64 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java @@ -26,9 +26,35 @@ public interface CommandStore { boolean existsByKey(String key); - boolean checkRequestInstanceByKey(String key, Class clazz); + /** + * @return everything needed to answer a repeated request exactly as the original one was answered - the state, and + * the status code and body it completed with. A command that completed, one that is still running and one + * that failed cannot be answered the same way, so the caller has to be able to tell them apart. Never + * {@code null}; an unknown key reports {@link CommandState#UNKNOWN}. + */ + CommandReplay getReplayByKey(String key); - T getResponseByKey(String key); + /** + * Records what the original request was answered with, for the parts a command cannot know: the status code always, + * and the body only when the command stored no result of its own. A stored result is never replaced, because a + * replay is rendered from that result rather than from captured text. + */ + void recordResponse(String key, int statusCode, String body); + + /** + * Atomically claims the command's idempotency key by persisting it, so that no other request can execute a command + * under the same key. Must not be retried, and the conflict must not be swallowed. + * + * @return {@code true} if the key was claimed by this call, {@code false} if it was already claimed + */ + boolean claim(Command command); + + /** + * @return {@code true} if the given payload is identical to the request stored under that idempotency key. + * Comparing the whole request, not just its type, is what stops a key reused for a different request from + * replaying an unrelated response. + */ + boolean matchesStoredRequest(String key, Object payload); void store(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java new file mode 100644 index 00000000000..92868fcbff7 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java @@ -0,0 +1,57 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +import lombok.Getter; + +/** + * Base of the answers given to a request that repeats an idempotency key. The request is never executed again; it is + * answered from what was stored for the original one, which is why every subclass carries a status code and a response + * rather than a message. + * + *

+ * The response is the command's own result object, rehydrated from the command store, not pre-rendered text. Handing + * the web layer an object lets it serialize the replay exactly as it serialized the original answer. + */ +@Getter +public abstract class AbstractCommandIdempotencyException extends RuntimeException { + + /** Set on every answer served from the command store, so a client can tell a replay from a fresh execution. */ + public static final String IDEMPOTENT_CACHE_HEADER = "x-served-from-cache"; + + private final String idempotencyKey; + private final int statusCode; + private final Object response; + + protected AbstractCommandIdempotencyException(String idempotencyKey, int statusCode, Object response) { + this(idempotencyKey, statusCode, response, null); + } + + /** + * Carries what went wrong underneath, for an answer that is given because the stored result could not be used + * rather than because it could. + */ + protected AbstractCommandIdempotencyException(String idempotencyKey, int statusCode, Object response, Throwable cause) { + super("Idempotency key " + idempotencyKey + " was already used; answering with the stored result (" + statusCode + ")", cause); + + this.idempotencyKey = idempotencyKey; + this.statusCode = statusCode; + this.response = response; + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java new file mode 100644 index 00000000000..f833ffb631e --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java @@ -0,0 +1,37 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats an idempotency key for a different request than the one stored under it. Replaying the + * stored response would answer a question that was never asked, so the request is rejected instead. + */ +public class CommandIdempotencyConflictException extends AbstractCommandIdempotencyException { + + /** 409 Conflict - the key is in use by a different request. */ + public static final int STATUS_CODE = 409; + + public CommandIdempotencyConflictException(String idempotencyKey, Object response) { + super(idempotencyKey, STATUS_CODE, response); + } + + public CommandIdempotencyConflictException(String idempotencyKey, Object response, Throwable cause) { + super(idempotencyKey, STATUS_CODE, response, cause); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java new file mode 100644 index 00000000000..9fd9d23d4e5 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java @@ -0,0 +1,31 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats the idempotency key of a command that failed. The original failure is replayed with the + * status it was first answered with, so a repeat fails exactly the way the original did. + */ +public class CommandIdempotencyFailedException extends AbstractCommandIdempotencyException { + + public CommandIdempotencyFailedException(String idempotencyKey, Integer statusCode, Object response) { + // an unknown status means the stored record is inconsistent; answering 500 beats answering nothing + super(idempotencyKey, statusCode == null ? 500 : statusCode, response); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java new file mode 100644 index 00000000000..93d24a5b3dd --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java @@ -0,0 +1,33 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats an idempotency key whose original command is still being processed. There is no result + * to replay yet, so the caller is told it asked too early and should come back. + */ +public class CommandIdempotencyInProgressException extends AbstractCommandIdempotencyException { + + /** 425 Too Early - the original command has not finished, so retrying is the right thing to do. */ + public static final int STATUS_CODE = 425; + + public CommandIdempotencyInProgressException(String idempotencyKey, Object response) { + super(idempotencyKey, STATUS_CODE, response); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java new file mode 100644 index 00000000000..752f8300f5c --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats the idempotency key of a command that completed. The original response is replayed with + * the status it was first answered with. + */ +public class CommandIdempotencyProcessedException extends AbstractCommandIdempotencyException { + + public CommandIdempotencyProcessedException(String idempotencyKey, Integer statusCode, Object response) { + super(idempotencyKey, statusCode == null ? 200 : statusCode, response); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java index 9ce7cd13ea2..9aceba02850 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java @@ -26,6 +26,11 @@ public final class ServletHeaderUtil { private ServletHeaderUtil() {} + /** + * Reads a header of the request being served on the current thread. Returns {@code null} off that + * thread, because {@link RequestContextHolder} is not inheritable - so anything calling this from an asynchronous + * dispatcher silently gets nothing. + */ public static String getHeader(String name, boolean searchParameter) { var attributes = RequestContextHolder.getRequestAttributes(); @@ -41,4 +46,25 @@ public static String getHeader(String name, boolean searchParameter) { return null; } + + /** + * Sets a header on the response being written on the current thread, and reports whether it could. + * Like {@link #getHeader(String, boolean)} this does nothing off that thread, and nothing once the response has + * been committed. + */ + public static boolean setResponseHeader(String name, String value) { + var attributes = RequestContextHolder.getRequestAttributes(); + + if (attributes instanceof ServletRequestAttributes servletAttributes) { + var response = servletAttributes.getResponse(); + + if (response != null && !response.isCommitted()) { + response.setHeader(name, value); + + return true; + } + } + + return false; + } } diff --git a/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java index ab7b5005078..1383f240c74 100644 --- a/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java +++ b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java @@ -101,14 +101,16 @@ void validation() { @Test void dummyApiSync() { final var content = "test-sync"; - // final var idempotencyKey = UUID.randomUUID().toString(); + final var idempotencyKey = UUID.randomUUID().toString(); restTemplate.setInterceptors(interceptors); - // final var headers = new HttpHeaders(); - // headers.add(properties.getIdemPotencyKeyHeaderName(), idempotencyKey); + // this module has no command store, so the key is only carried, not acted on; the idempotency behaviour itself + // is covered by IdempotencyCheckCommandHookTest and JdbcCommandStoreTest + final var headers = new HttpHeaders(); + headers.add("Idempotency-Key", idempotencyKey); - final var request = new HttpEntity<>(DummyRequest.builder().content(content).build(), new HttpHeaders()); + final var request = new HttpEntity<>(DummyRequest.builder().content(content).build(), headers); final var result = restTemplate.postForObject(baseUrl + "/sync", request, DummyResponse.class); @@ -118,20 +120,10 @@ void dummyApiSync() { assertNotNull(result.getContent(), "Response body should not be null."); assertEquals(content.toUpperCase(Locale.ROOT), result.getContent(), "Wrong response content."); - // DummyResponse response = store.getResponseByKey(idempotencyKey); - // - // assertNotNull(response, "There should be a command entity stored with a response."); - // assertNotNull(response, "Response should not be null."); - // assertNotNull(response.getContent(), "Response body should not be null."); - // assertNotNull(response.getTenantId(), "Tenant ID should not be null."); - // assertEquals("dummy", response.getTenantId(), "Unexpected tenant ID."); - // assertEquals(content.toUpperCase(Locale.ROOT), response.getContent(), "Wrong response content."); - // - // log.warn("Command response: {}", response); } @Test - @Disabled // TODO: implement idempotency properly with backwards compatibility + @Disabled // needs a command store; see JdbcCommandStoreTest and IdempotencyCheckCommandHookTest void dummyApiIdempotencySync() { dummyApiIdempotency("/sync"); } diff --git a/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java b/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java new file mode 100644 index 00000000000..6bbb6e0e2c4 --- /dev/null +++ b/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java @@ -0,0 +1,74 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertSame; + +import org.junit.jupiter.api.Test; + +/** + * The status codes and header below are the contract the old command processing already answers with, so a client that + * works against it keeps working against the new one. + */ +class CommandIdempotencyExceptionTest { + + private static final String KEY = "7f3a1c04"; + + @Test + void theReplayHeaderMatchesTheOneTheOldProcessingUses() { + assertEquals("x-served-from-cache", AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER, + "Changing this header name would break every client that checks for a replay."); + } + + @Test + void anUnfinishedCommandAnswersTooEarly() { + var stored = new Object(); + var exception = new CommandIdempotencyInProgressException(KEY, stored); + + assertEquals(425, exception.getStatusCode(), "An unfinished command must answer 425 Too Early."); + assertSame(stored, exception.getResponse(), "The answer carries the result object, which the web layer renders."); + assertEquals(KEY, exception.getIdempotencyKey(), "The answer must name the key it is about."); + } + + @Test + void aProcessedCommandReplaysItsOwnStatus() { + assertEquals(201, new CommandIdempotencyProcessedException(KEY, 201, new Object()).getStatusCode(), + "A replay must answer with the status the original was answered with."); + assertEquals(200, new CommandIdempotencyProcessedException(KEY, null, new Object()).getStatusCode(), + "A processed command with no recorded status falls back to 200."); + } + + @Test + void aFailedCommandReplaysItsOwnFailure() { + var stored = new Object(); + var exception = new CommandIdempotencyFailedException(KEY, 400, stored); + + assertEquals(400, exception.getStatusCode(), "A repeat of a failed command must fail the same way."); + assertSame(stored, exception.getResponse(), "A repeat of a failed command carries whatever was stored for it."); + assertEquals(500, new CommandIdempotencyFailedException(KEY, null, null).getStatusCode(), + "An inconsistent record answers 500 rather than nothing at all."); + } + + @Test + void aKeyUsedForAnotherRequestConflicts() { + assertEquals(409, new CommandIdempotencyConflictException(KEY, null).getStatusCode(), + "Reusing a key for a different request is a conflict, not a replay."); + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java index 2528d818f8e..71db6ca9fd3 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java @@ -18,6 +18,7 @@ */ package org.apache.fineract.organisation.workingdays.handler; +import io.github.resilience4j.retry.annotation.Retry; import java.util.Collections; import java.util.Map; import lombok.RequiredArgsConstructor; @@ -37,6 +38,7 @@ public class UpdateWorkingDaysCommandHandler implements CommandHandler command) { @@ -52,4 +54,8 @@ public WorkingDaysUpdateResponse handle(Command comman .extendTermForRepaymentsOnHolidays(request.getExtendTermForRepaymentsOnHolidays()).build(); } + @Override + public WorkingDaysUpdateResponse fallback(Command command, Throwable t) { + return CommandHandler.super.fallback(command, t); + } } diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index 3fbbda00389..fdde5a1a1ed 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -590,6 +590,8 @@ fineract.retry.instances.inlineCob.wait-duration=${FINERACT_INLINE_COB_RETRY_WAI fineract.retry.instances.inlineCob.enable-exponential-backoff=${FINERACT_INLINE_COB_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} fineract.retry.instances.inlineCob.exponential-backoff-multiplier=${FINERACT_INLINE_COB_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} + + resilience4j.retry.instances.processJobDetailForExecution.max-attempts=${FINERACT_PROCESS_JOB_DETAIL_RETRY_MAX_ATTEMPTS:3} resilience4j.retry.instances.processJobDetailForExecution.wait-duration=${FINERACT_PROCESS_JOB_DETAIL_RETRY_WAIT_DURATION:1s} resilience4j.retry.instances.processJobDetailForExecution.enable-exponential-backoff=${FINERACT_PROCESS_JOB_DETAIL_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} @@ -615,6 +617,11 @@ resilience4j.retry.instances.commandBusinessDateUpdate.wait-duration=${FINERACT_ resilience4j.retry.instances.commandBusinessDateUpdate.enable-exponential-backoff=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} resilience4j.retry.instances.commandBusinessDateUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} resilience4j.retry.instances.commandBusinessDateUpdate.retryExceptions=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} +resilience4j.retry.instances.commandWorkingDaysUpdate.max-attempts=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandWorkingDaysUpdate.wait-duration=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandWorkingDaysUpdate.enable-exponential-backoff=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandWorkingDaysUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandWorkingDaysUpdate.retryExceptions=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} # cache @@ -914,7 +921,13 @@ resilience4j.retry.instances.commandStore.max-attempts=${FINERACT_COMMAND_STORE_ resilience4j.retry.instances.commandStore.wait-duration=${FINERACT_COMMAND_STORE_RETRY_WAIT_DURATION:1s} resilience4j.retry.instances.commandStore.enable-exponential-backoff=${FINERACT_COMMAND_STORE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} resilience4j.retry.instances.commandStore.exponential-backoff-multiplier=${FINERACT_COMMAND_STORE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} -resilience4j.retry.instances.commandStore.retryExceptions=${FINERACT_COMMAND_STORE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} +# The command row is written on the idempotency path, where a deadlock or a connection dropped mid-flight +# is a reason to try again rather than to give up: retrying cannot write the row twice, because the key is +# unique. A constraint violation is the opposite - the row is already there - and is ignored explicitly so +# that widening the list later cannot start retrying it by accident. Deliberately only this instance: the +# COB and interest jobs must not retry on a connection lost during commit, where the outcome is unknown. +resilience4j.retry.instances.commandStore.retryExceptions=${FINERACT_COMMAND_STORE_RETRY_EXCEPTIONS:org.springframework.dao.TransientDataAccessException,org.springframework.dao.RecoverableDataAccessException,java.sql.SQLTransientException,java.sql.SQLRecoverableException,jakarta.persistence.OptimisticLockException,jakarta.persistence.PessimisticLockException,jakarta.persistence.LockTimeoutException,jakarta.persistence.QueryTimeoutException,org.eclipse.persistence.exceptions.OptimisticLockException} +resilience4j.retry.instances.commandStore.ignoreExceptions=${FINERACT_COMMAND_STORE_RETRY_IGNORE_EXCEPTIONS:org.springframework.dao.DataIntegrityViolationException,jakarta.persistence.EntityExistsException} # Retry for the lookups every request needs before it can run (tenant and business dates), so a short database outage # or a connection pool timeout does not fail the request. Each attempt can wait for the pool connection timeout. diff --git a/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java new file mode 100644 index 00000000000..baabf1138da --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java @@ -0,0 +1,98 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command; + +import static org.assertj.core.api.Assertions.assertThat; + +import io.github.resilience4j.retry.annotation.Retry; +import java.lang.reflect.Method; +import java.util.ArrayList; +import java.util.List; +import org.apache.fineract.command.core.CommandHandler; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.config.BeanDefinition; +import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider; +import org.springframework.core.type.filter.AssignableTypeFilter; + +/** + * Holds every command handler to the retry policy, so that executing a command is as resilient as recording it. + * + *

+ * Retrying is applied per handler rather than once around the dispatcher, because each command gets its own policy to + * tune and because the retry has to sit outside the handler's own transaction - a second attempt inside a transaction + * already marked for rollback would achieve nothing. The cost of that arrangement is that a new handler is retried only + * if somebody remembers to say so, and nothing fails when they do not: the command simply gives up on the first + * contention, where its neighbours would have tried again. + * + *

+ * This is the reminder. It walks every {@link CommandHandler} on the classpath rather than a list that would itself + * need maintaining. + */ +class CommandHandlerRetryCoverageTest { + + /** + * The sample handlers that exist to exercise the framework, including one that is deliberately made to fail. They + * are not commands the application serves. + */ + private static final String SAMPLE_HANDLERS = "org.apache.fineract.command.test"; + + @Test + void everyCommandHandlerRetriesItsExecution() { + var withoutRetry = new ArrayList(); + + for (Class handler : commandHandlers()) { + if (handler.getName().startsWith(SAMPLE_HANDLERS)) { + continue; + } + + if (handleMethodOf(handler).map(method -> method.getAnnotation(Retry.class)).isEmpty()) { + withoutRetry.add(handler.getSimpleName()); + } + } + + assertThat(withoutRetry).as("These handlers execute their command without a retry, so they give up on the first contention " + + "where every other command tries again. Add @Retry(name = \"commandXxx\", fallbackMethod = " + + "\"fallback\") and configure that instance in application.properties.").isEmpty(); + } + + private static java.util.Optional handleMethodOf(Class handler) { + return java.util.Arrays.stream(handler.getDeclaredMethods()) + .filter(method -> "handle".equals(method.getName()) && !method.isSynthetic()).findFirst(); + } + + private static List> commandHandlers() { + var scanner = new ClassPathScanningCandidateComponentProvider(false); + + scanner.addIncludeFilter(new AssignableTypeFilter(CommandHandler.class)); + + var found = new ArrayList>(); + + for (BeanDefinition definition : scanner.findCandidateComponents("org.apache.fineract")) { + try { + found.add(Class.forName(definition.getBeanClassName())); + } catch (ClassNotFoundException e) { + throw new IllegalStateException("Scanned a handler that cannot be loaded: " + definition.getBeanClassName(), e); + } + } + + assertThat(found).as("The scan must actually find the handlers, or this test passes by finding nothing.").isNotEmpty(); + + return found; + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapperJerseyTest.java b/fineract-provider/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapperJerseyTest.java new file mode 100644 index 00000000000..4bc70bc4df9 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionMapperJerseyTest.java @@ -0,0 +1,123 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.junit.jupiter.api.Assertions.assertEquals; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import java.io.ByteArrayOutputStream; +import java.net.URI; +import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; +import org.glassfish.jersey.internal.MapPropertiesDelegate; +import org.glassfish.jersey.server.ApplicationHandler; +import org.glassfish.jersey.server.ContainerRequest; +import org.glassfish.jersey.server.ResourceConfig; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.context.annotation.AnnotationConfigApplicationContext; + +/** + * Runs a replayed failure through a real Jersey stack, because the answer a client receives depends on how Jersey + * writes the entity rather than on what the mapper puts in it. + * + *

+ * The stored answer for a failure is the text that was captured as it went out, so the mapper hands Jersey a + * {@code String}. Were Jersey to treat that as a value to serialise rather than as a body to write, a client would + * receive {@code "{\"errors\":[...]}"} - the original document wrapped in quotes and escaped - instead of the document + * itself. That is the difference this pins, and no test of the mapper on its own can see it: the mapper is correct + * either way. + * + *

+ * The end-to-end suite covers the Spring MVC counterpart; Fineract itself serves its API through Jersey, which is this. + */ +class IdempotencyCommandExceptionMapperJerseyTest { + + private static final String STORED_ANSWER = """ + {"developerMessage":"The request was invalid.","httpStatusCode":"400","errors":[{"parameterName":"principal",\ + "defaultUserMessage":"The parameter principal cannot be blank.","value":null}],"amount":1.50}"""; + + private ApplicationHandler handler; + + @BeforeEach + void startJersey() { + // built here rather than in a field, because standing a Jersey application up can fail and a constructor that + // throws is a finding of its own + handler = new ApplicationHandler(resourceConfig()); + } + + /** + * Jersey's Spring bridge is on the classpath and looks for a context of its own; an empty one keeps it satisfied + * without dragging an application context into a test about how bytes reach the wire. + */ + private static ResourceConfig resourceConfig() { + var springContext = new AnnotationConfigApplicationContext(); + + springContext.refresh(); + + return new ResourceConfig().property("contextConfig", springContext).register(IdempotencyCommandExceptionMapper.class) + .register(ReplayResource.class); + } + + @Test + void aReplayedFailureIsWrittenAsTheDocumentItIsRatherThanAsAQuotedString() throws Exception { + var body = new ByteArrayOutputStream(); + + var response = handler.apply(request("/failed"), body).get(); + + assertEquals(400, response.getStatus(), "A repeat of a failure must answer with the status it was first answered with."); + assertEquals("true", response.getStringHeaders().getFirst(IDEMPOTENT_CACHE_HEADER), + "A replay must tell the client it was served from the command store."); + assertEquals(STORED_ANSWER, body.toString(UTF_8), + "The client must receive the stored answer byte for byte, not a JSON string containing it."); + } + + @Test + void aFailureWithNothingStoredAnswersWithItsStatusAndAnEmptyBody() throws Exception { + var body = new ByteArrayOutputStream(); + + var response = handler.apply(request("/nothing-stored"), body).get(); + + assertEquals(500, response.getStatus(), "An inconsistent record answers 500 rather than nothing at all."); + assertEquals("", body.toString(UTF_8), "There is nothing to replay, so the body is empty rather than \"null\"."); + } + + private static ContainerRequest request(String path) { + return new ContainerRequest(URI.create("http://localhost/"), URI.create("http://localhost" + path), "GET", null, + new MapPropertiesDelegate(), null); + } + + @Path("/") + public static class ReplayResource { + + @GET + @Path("failed") + public String failed() { + throw new CommandIdempotencyFailedException("a-key", 400, STORED_ANSWER); + } + + @GET + @Path("nothing-stored") + public String nothingStored() { + throw new CommandIdempotencyFailedException("a-key", null, null); + } + } +} diff --git a/fineract-provider/src/test/resources/application-test.properties b/fineract-provider/src/test/resources/application-test.properties index b9851c21e1d..662a2ee90ae 100644 --- a/fineract-provider/src/test/resources/application-test.properties +++ b/fineract-provider/src/test/resources/application-test.properties @@ -365,6 +365,10 @@ fineract.command.audit.enabled=true fineract.command.audit.hook-pre-enabled=true fineract.command.audit.hook-post-enabled=true fineract.command.audit.hook-error-enabled=true +fineract.command.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true fineract.command.hook-servlet-headers-enabled=true fineract.command.hook-timestamp-enabled=true fineract.command.hook-username-enabled=true From 3caa656ca973ec29362160d7dadb2c98fa8c56e9 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Mon, 9 Nov 2026 19:07:29 +0000 Subject: [PATCH 05/11] FINERACT-2485: Require auditing when idempotency is enabled The audit hooks own the command row: they move a claimed command out of UNDER_PROCESSING and store its result. With auditing off, a claimed key would stay UNDER_PROCESSING for ever and every repeat would be answered 425 - visible only from the second request. An application configured that way now refuses to start. Both features default to enabled. --- .../command/audit/AuditCommandConstants.java | 5 +- .../command/audit/AuditCommandProperties.java | 6 + .../check/AuditCommandPropertyCheck.java | 43 ++++---- .../audit/hook/AuditCommandHookAfter.java | 2 +- .../audit/hook/AuditCommandHookBefore.java | 2 +- .../audit/hook/AuditCommandHookError.java | 10 +- .../AuditCommandAutoConfiguration.java | 2 +- ...CommandPropertyCheckAutoConfiguration.java | 8 +- .../check/AuditCommandPropertyCheckTest.java | 103 ++++++++++++++++++ .../dependencies.gradle | 27 +++++ .../IdempotencyCommandProperties.java | 12 +- .../IdempotencyCommandPropertyCheck.java | 68 ++++++++++++ ...CommandPropertyCheckAutoConfiguration.java | 35 ++++++ ...ot.autoconfigure.AutoConfiguration.imports | 1 + .../IdempotencyCommandPropertyCheckTest.java | 65 +++++++++++ 15 files changed, 359 insertions(+), 30 deletions(-) create mode 100644 fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java index 9dc48376e58..98fb754aa35 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java @@ -29,8 +29,9 @@ private AuditCommandConstants() {} public static final String COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-pre-enabled"; public static final String COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-post-enabled"; public static final String COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED = COMMAND_AUDIT_PROPERTIES_PREFIX + ".hook-error-enabled"; - public static final String COMMAND_AUDIT_HOOK_BASE_PACKAGE = "org.apache.fineract.command.audit.hook"; - public static final String COMMAND_AUDIT_HOOK_CHECK_PACKAGE = COMMAND_AUDIT_HOOK_BASE_PACKAGE + ".check"; + public static final String COMMAND_AUDIT_BASE_PACKAGE = "org.apache.fineract.command.audit"; + public static final String COMMAND_AUDIT_HOOK_BASE_PACKAGE = COMMAND_AUDIT_BASE_PACKAGE + ".hook"; + public static final String COMMAND_AUDIT_CHECK_BASE_PACKAGE = COMMAND_AUDIT_BASE_PACKAGE + ".check"; public static final int COMMAND_AUDIT_HOOK_BEFORE = 30; public static final int COMMAND_AUDIT_HOOK_AFTER = 30; public static final int COMMAND_AUDIT_HOOK_ERROR = 30; diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java index ac5eb45393e..75a46145a23 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java @@ -40,6 +40,12 @@ public final class AuditCommandProperties implements Serializable { @Serial private static final long serialVersionUID = 1L; + /** + * Auditing is on as soon as the module is on the classpath; it has to be switched off explicitly. Losing the audit + * trail should be a decision, not the consequence of an unset property. These defaults are kept in step with + * {@code matchIfMissing} on the corresponding {@code @ConditionalOnProperty}; changing one without the other makes + * this class describe behaviour the application does not have. + */ @Builder.Default private Boolean enabled = true; @Builder.Default diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java index c97b4c1b129..38af9182f4c 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java @@ -18,39 +18,44 @@ */ package org.apache.fineract.command.audit.check; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED; - import jakarta.annotation.PostConstruct; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.springframework.core.env.Environment; +import org.apache.fineract.command.audit.AuditCommandProperties; import org.springframework.stereotype.Component; +/** + * Reports at startup whether command auditing is actually switched on. Reads the bound property values rather than + * testing for their presence, so that an explicit {@code false} is reported as disabled. + */ @Slf4j @RequiredArgsConstructor @Component final class AuditCommandPropertyCheck { - private final Environment environment; + private static final String RECOMMENDATION = "IT IS RECOMMENDED TO ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"; + + private final AuditCommandProperties properties; @PostConstruct - public void check() { - if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED)) { - log.info("Audit pre command hook enabled."); - } else { - log.warn("Audit pre command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); - } - if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED)) { - log.info("Audit post command hook enabled."); - } else { - log.warn("Audit post command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); + void check() { + if (!Boolean.TRUE.equals(properties.getEnabled())) { + log.warn("Command audit is disabled! {}", RECOMMENDATION); + + // the individual hooks are not created at all while the module is disabled + return; } - if (environment.containsProperty(COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED)) { - log.info("Audit error command hook enabled."); + + report("pre", properties.getHookPreEnabled()); + report("post", properties.getHookPostEnabled()); + report("error", properties.getHookErrorEnabled()); + } + + private void report(String hook, Boolean enabled) { + if (Boolean.TRUE.equals(enabled)) { + log.info("Audit {} command hook enabled.", hook); } else { - log.warn("Audit error command hook disabled! IT IS RECOMMENDED ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"); + log.warn("Audit {} command hook disabled! {}", hook, RECOMMENDATION); } } } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java index d315741c672..d871b7829d5 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java @@ -35,7 +35,7 @@ @RequiredArgsConstructor @Component @Order(COMMAND_AUDIT_HOOK_AFTER) -@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, havingValue = "true", matchIfMissing = false) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, havingValue = "true", matchIfMissing = true) final class AuditCommandHookAfter implements CommandHookAfter { private final CommandStore store; diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java index 6b303c46a52..aac22252608 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java @@ -36,7 +36,7 @@ @RequiredArgsConstructor @Component @Order(COMMAND_AUDIT_HOOK_BEFORE) -@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED, havingValue = "true") +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED, havingValue = "true", matchIfMissing = true) final class AuditCommandHookBefore implements CommandHookBefore { private final CommandStore store; diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java index 7179b3e8eb3..dff61cf3520 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java @@ -36,13 +36,21 @@ @RequiredArgsConstructor @Component @Order(COMMAND_AUDIT_HOOK_ERROR) -@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, havingValue = "true") +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, havingValue = "true", matchIfMissing = true) final class AuditCommandHookError implements CommandHookError { private final CommandStore store; @Override public void onError(CommandContext ctx) { + if (ctx.isSkipExecution()) { + // the command was never executed, so there is no execution to audit. Storing it here would also collide + // with the record that already owns this command's idempotency key. + log.debug("Skipping error audit for a command that was not executed"); + + return; + } + final var now = Instant.now(); ctx.setState(ERROR); diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java index 366e94a3b1a..c11c5c49fdc 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java @@ -31,5 +31,5 @@ @AutoConfiguration @EnableConfigurationProperties({ CommandProperties.class, AuditCommandProperties.class }) @ComponentScan(COMMAND_AUDIT_HOOK_BASE_PACKAGE) -@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_ENABLED, havingValue = "true") +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_ENABLED, havingValue = "true", matchIfMissing = true) public class AuditCommandAutoConfiguration {} diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java index 8eb8709c78f..82b3435b7dc 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java @@ -18,11 +18,15 @@ */ package org.apache.fineract.command.audit.starter; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_CHECK_PACKAGE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_CHECK_BASE_PACKAGE; +import org.apache.fineract.command.audit.AuditCommandProperties; import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.ComponentScan; +// note: deliberately not conditional on the audit properties; the point is to report when auditing is off @AutoConfiguration -@ComponentScan(COMMAND_AUDIT_HOOK_CHECK_PACKAGE) +@EnableConfigurationProperties(AuditCommandProperties.class) +@ComponentScan(COMMAND_AUDIT_CHECK_BASE_PACKAGE) public class AuditCommandPropertyCheckAutoConfiguration {} diff --git a/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java b/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java new file mode 100644 index 00000000000..ece385ac7dd --- /dev/null +++ b/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java @@ -0,0 +1,103 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.audit.check; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; + +import org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration; +import org.apache.fineract.command.audit.starter.AuditCommandPropertyCheckAutoConfiguration; +import org.apache.fineract.command.core.CommandHookAfter; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.core.CommandHookError; +import org.apache.fineract.command.core.CommandStore; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.boot.test.system.CapturedOutput; +import org.springframework.boot.test.system.OutputCaptureExtension; + +@ExtendWith(OutputCaptureExtension.class) +class AuditCommandPropertyCheckTest { + + private final ApplicationContextRunner runner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(AuditCommandPropertyCheckAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)); + + @Test + void theCheckIsRegisteredSoThatItCanActuallyReport(CapturedOutput output) { + runner.run(context -> { + assertThat(context).hasSingleBean(AuditCommandPropertyCheck.class); + assertThat(output).contains("Audit pre command hook enabled."); + }); + } + + @Test + void auditingIsOnWhenNothingIsConfigured(CapturedOutput output) { + // losing the audit trail must be a decision, not the consequence of an unset property + runner.run(context -> { + assertThat(output).contains("Audit pre command hook enabled."); + assertThat(output).contains("Audit post command hook enabled."); + assertThat(output).contains("Audit error command hook enabled."); + assertThat(output).doesNotContain("disabled!"); + }); + } + + @Test + void anExplicitlyDisabledHookIsReportedAsDisabled(CapturedOutput output) { + runner.withPropertyValues("fineract.command.audit.hook-pre-enabled=false", "fineract.command.audit.hook-post-enabled=false", + "fineract.command.audit.hook-error-enabled=false").run(context -> { + assertThat(output).contains("Audit pre command hook disabled!"); + assertThat(output).contains("Audit post command hook disabled!"); + assertThat(output).contains("Audit error command hook disabled!"); + assertThat(output).doesNotContain("command hook enabled."); + }); + } + + @Test + void anExplicitlyDisabledModuleIsReportedAsDisabled(CapturedOutput output) { + runner.withPropertyValues("fineract.command.audit.enabled=false").run(context -> { + assertThat(context).hasSingleBean(AuditCommandPropertyCheck.class); + assertThat(output).contains("Command audit is disabled!"); + }); + } + + @Test + void theReportedDefaultsMatchTheHooksThatAreActuallyCreated() { + // guards against the properties class describing behaviour the application does not have + new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(AuditCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)).run(context -> { + assertThat(context).hasSingleBean(CommandHookBefore.class); + assertThat(context).hasSingleBean(CommandHookAfter.class); + assertThat(context).hasSingleBean(CommandHookError.class); + }); + } + + @Test + void noHooksAreCreatedWhenTheModuleIsExplicitlyDisabled() { + new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(AuditCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)).withPropertyValues("fineract.command.audit.enabled=false") + .run(context -> { + assertThat(context).doesNotHaveBean(CommandHookBefore.class); + assertThat(context).doesNotHaveBean(CommandHookAfter.class); + assertThat(context).doesNotHaveBean(CommandHookError.class); + }); + } +} diff --git a/fineract-command-idempotency/dependencies.gradle b/fineract-command-idempotency/dependencies.gradle index 9bb49133333..6476737b71c 100644 --- a/fineract-command-idempotency/dependencies.gradle +++ b/fineract-command-idempotency/dependencies.gradle @@ -20,13 +20,40 @@ dependencies { implementation( project(path: ':fineract-command'), + // a claimed command is moved out of UNDER_PROCESSING, and its result stored, by the audit hooks; this + // module cannot replay anything without them, and says so at startup + project(path: ':fineract-command-audit'), ) implementation( 'org.springframework.boot:spring-boot-starter', + // the key arrives on an HTTP header and the original response is replayed over HTTP, so this module + // owns a servlet filter and a JAX-RS exception mapper + 'org.springframework.boot:spring-boot-starter-webmvc', + 'jakarta.ws.rs:jakarta.ws.rs-api', 'org.apache.commons:commons-lang3', ) compileOnly 'org.projectlombok:lombok' annotationProcessor 'org.projectlombok:lombok' + + testImplementation( + project(path: ':fineract-command-test'), + project(path: ':fineract-command-jdbc'), + ) + testImplementation ( + 'org.springframework.boot:spring-boot-starter-data-jdbc', + // Spring Boot 4 ships the Liquibase auto-configuration separately; the schema under test comes from it + 'org.springframework.boot:spring-boot-liquibase', + 'org.liquibase:liquibase-core', + 'org.testcontainers:junit-jupiter', + 'org.testcontainers:postgresql', + ) + testImplementation ('org.springframework.boot:spring-boot-starter-test') { + exclude group: 'com.jayway.jsonpath', module: 'json-path' + exclude group: 'org.junit.vintage', module: 'junit-vintage-engine' + exclude group: 'jakarta.activation' + exclude group: 'javax.activation' + exclude group: 'org.skyscreamer' + } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java index 207390b1b3a..1b57c80acb2 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java @@ -40,14 +40,20 @@ public final class IdempotencyCommandProperties implements Serializable { @Serial private static final long serialVersionUID = 1L; + /** + * Idempotency is on as soon as the module is on the classpath; it has to be switched off explicitly. A repeated + * request quietly executing twice should be a decision, not the consequence of an unset property. These defaults + * are kept in step with {@code matchIfMissing} on the corresponding {@code @ConditionalOnProperty}; changing one + * without the other makes this class describe behaviour the application does not have. + */ @Builder.Default - private Boolean enabled = false; + private Boolean enabled = true; @Builder.Default - private Boolean hookKeyHeaderPre = false; + private Boolean hookKeyHeaderPre = true; @Builder.Default - private Boolean hookCheckPre = false; + private Boolean hookCheckPre = true; @Builder.Default private String keyHeaderName = "Idempotency-Key"; diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java new file mode 100644 index 00000000000..6369ec6f2ee --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java @@ -0,0 +1,68 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.check; + +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_ENABLED; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; + +import jakarta.annotation.PostConstruct; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.audit.AuditCommandProperties; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.stereotype.Component; + +/** + * Refuses to start an application that has idempotency switched on and auditing switched off. + * + *

+ * Claiming an idempotency key writes the command row, but nothing in this module ever writes it again: it is the audit + * hooks that move a claimed command out of {@code UNDER_PROCESSING} and store the result a repeat is answered with. Run + * idempotency without them and the first request for a key succeeds, the row stays {@code UNDER_PROCESSING} for ever, + * and every repeat of that key is answered {@code 425 Too Early} - the key is poisoned, silently, and only from the + * second request onwards. That is worth failing a startup over rather than warning about. + */ +@Slf4j +@RequiredArgsConstructor +@Component +final class IdempotencyCommandPropertyCheck { + + private final IdempotencyCommandProperties idempotency; + + private final AuditCommandProperties audit; + + @PostConstruct + void check() { + if (!Boolean.TRUE.equals(idempotency.getEnabled())) { + log.info("Command idempotency is disabled: commands are still audited, but no idempotency key is read and " + + "a repeated request is executed again rather than replayed."); + + return; + } + + if (!Boolean.TRUE.equals(audit.getEnabled())) { + throw new IllegalStateException("Command idempotency is enabled but command auditing is not: " + COMMAND_AUDIT_PROPERTY_ENABLED + + " must be true. Idempotency relies on the audit hooks to record how a " + + "command finished; without them every repeat of an idempotency key would be answered 425 Too Early for " + + "ever. Enable auditing, or set " + COMMAND_IDEMPOTENCY_PROPERTY_ENABLED + "=false."); + } + + log.info("Command idempotency is enabled."); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java new file mode 100644 index 00000000000..526aa0d97aa --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.starter; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE; + +import org.apache.fineract.command.audit.AuditCommandProperties; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.context.annotation.ComponentScan; + +// note: deliberately not conditional on the idempotency properties; the check has to see the combination that would +// otherwise switch this module off, and it binds the audit properties itself so that it can read them while the audit +// module is disabled and its own auto-configuration has backed off +@AutoConfiguration +@EnableConfigurationProperties({ IdempotencyCommandProperties.class, AuditCommandProperties.class }) +@ComponentScan(COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE) +public class IdempotencyCommandPropertyCheckAutoConfiguration {} diff --git a/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports index 57527f50053..d6d52cdcebe 100644 --- a/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports +++ b/fineract-command-idempotency/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports @@ -1 +1,2 @@ org.apache.fineract.command.idempotency.starter.IdempotencyCommandAutoConfiguration +org.apache.fineract.command.idempotency.starter.IdempotencyCommandPropertyCheckAutoConfiguration diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java new file mode 100644 index 00000000000..b4cfa6882eb --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java @@ -0,0 +1,65 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.check; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.apache.fineract.command.idempotency.starter.IdempotencyCommandPropertyCheckAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * Covers the four ways idempotency and auditing can be configured against each other. + * + *

+ * Only one of them is a mistake, and it is the one that would otherwise go unnoticed: idempotency on, auditing off. + * Nothing fails at startup, the first request for a key is answered normally, and the breakage shows up only when a + * client retries - as a 425 that never resolves. The point of the check is to turn that into a startup failure. + */ +class IdempotencyCommandPropertyCheckTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(IdempotencyCommandPropertyCheckAutoConfiguration.class)); + + @Test + void bothOnIsTheDefaultAndStarts() { + contextRunner.run(context -> assertThat(context) + .as("Idempotency and auditing are both on unless switched off, which is the supported arrangement.").hasNotFailed()); + } + + @Test + void auditingOnItsOwnStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false").run(context -> assertThat(context) + .as("Auditing without idempotency is fine: commands are recorded, no key is read, nothing is replayed.").hasNotFailed()); + } + + @Test + void idempotencyWithoutAuditingRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.enabled=false").run(context -> assertThat(context) + .as("A claimed key would never leave UNDER_PROCESSING, so every repeat would answer 425 for ever.").hasFailed().getFailure() + .rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("fineract.command.audit.enabled")); + } + + @Test + void bothOffStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.enabled=false").run( + context -> assertThat(context).as("Neither feature is on, so nothing is written to the command table.").hasNotFailed()); + } +} From 0080f249ed6a0f8816fb6f6d0d7f489c7f2e847f Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Mon, 9 Nov 2026 19:07:30 +0000 Subject: [PATCH 06/11] FINERACT-2485: Document command auditing and idempotency behaviour --- .../chapters/architecture/command-audit.adoc | 110 +++++++++++++++++ .../en/chapters/architecture/idempotency.adoc | 111 +++++++++++++++++- .../docs/en/chapters/architecture/index.adoc | 2 + 3 files changed, 219 insertions(+), 4 deletions(-) create mode 100644 fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc diff --git a/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc new file mode 100644 index 00000000000..895beca27c9 --- /dev/null +++ b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc @@ -0,0 +1,110 @@ += Command auditing + +Every command dispatched through the new command processing is recorded in the `m_command` table by the +`fineract-command-audit` module. The record is written before the command runs and updated as it finishes, so a command +that is still in flight, one that completed and one that failed are all distinguishable afterwards. + +Auditing is on as soon as the module is on the classpath. Losing the audit trail should be a decision rather than the +consequence of an unset property. + +[source,properties] +---- +fineract.command.audit.enabled=true +fineract.command.audit.hook-pre-enabled=true +fineract.command.audit.hook-post-enabled=true +fineract.command.audit.hook-error-enabled=true +---- + +NOTE: With auditing switched off, nothing is written to `m_command` at all - and idempotency cannot be used, because it +is these hooks that record how a command finished. See <>. + +== How a command is recorded + +Auditing is implemented as three command hooks, which run after the idempotency hooks: + +[cols="1,1,3"] +|=== +| Hook | State written | When + +| Before +| `UNDER_PROCESSING` +| The command has been accepted and is about to run. + +| After +| `PROCESSED` +| The command returned. Its result is stored, along with `executed_at` and `executed_by_username`. + +| Error +| `ERROR` +| The command threw. The exception message is stored in the `error` column. +|=== + +A command that was never executed - a repeat of an idempotency key, which is answered from the existing record - is not +audited again. The record that owns the key already describes the command, and writing a second one would claim an +execution that never happened. + +== What is stored + +[cols="1,3"] +|=== +| Column | Content + +| `state` +| `UNDER_PROCESSING`, `PROCESSED` or `ERROR`. `UNKNOWN` is reported for a key that has no record at all. + +| `request` +| The command's payload, as JSON. + +| `response` +| The result the command produced, as JSON, carrying a type attribute so that it can be read back as the object it was. + +| `error` +| The message of the exception a failed command threw. + +| `initiated_by_username`, `executed_by_username` +| Who asked for the command, and who it ran as. + +| `created_at`, `updated_at`, `executed_at` +| When the record was written, last changed, and when the command ran. + +| `ip_address` +| Where the request came from. + +| `idempotency_key` +| The key the command was claimed under. See the idempotency chapter. + +| `response_status_code` +| Only set for a command that produced no result of its own. See the idempotency chapter. +|=== + +WARNING: `executed_at` and `executed_by_username` are written by the before hook as well as the after hook, so they are +set even for a command that failed or never finished. Read them as "when this record was last worked on" rather than as +proof that the command ran to completion; `state` is what says that. + +== Reliability + +Every write to `m_command` is retried, so that a command is not left recorded in the wrong state because of a deadlock +or a connection dropped mid-flight. A failure is retried when running the same call again could succeed, and never when +it could not - a constraint violation is a verdict, not a mishap, and is excluded explicitly. + +This wider list is set on the command store alone, under `resilience4j.retry.instances.commandStore`. Retrying a write +of the command row is safe because the idempotency key is unique, so a second attempt cannot write it twice. The same +is not true elsewhere: a connection lost during a commit leaves the outcome of that commit unknown, which is why the +jobs that post interest and run close-of-business keep the narrower list they already had. + +If the writes still fail after their attempts are spent, the command itself is unaffected: it has already been +processed and answered. A record that could not be written is logged, and, when the dead-letter queue is enabled, the +command is written to it so that the trail can be reconstructed. + +== Relationship with idempotency + +The audit hooks own the lifecycle of the command record. Idempotency claims the key and counts repeats, but it is the +audit hooks that move a command out of `UNDER_PROCESSING` and store what it produced. + +That makes auditing a prerequisite rather than a companion. An application configured with idempotency enabled and +auditing disabled refuses to start, naming the properties that conflict. Were it allowed to run, the first request +under a key would be answered normally, its record would stay `UNDER_PROCESSING` for ever, and every repeat of that key +would be answered `425 Too Early` - a failure that only appears on the second request and never resolves. + +The reverse is fine and is a supported arrangement: auditing without idempotency records every command as usual, reads +no idempotency key, and executes a repeated request again rather than replaying it. diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index d172967a3c9..d0b0f95313c 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -1,7 +1,5 @@ = Idempotency -IMPORTANT: The idempotency mechanics of the new command processing infrastructure still need to be documented. The implementation is done as a command hook. Detailed documentation will be provided soon. The only thing that new and legacy idempotency capabilities have in common is the name and configuration of the HTTP header name that contains the idempotency key. - Idempotency is the way to make sure your specific action is only executed once. For example, if you have a button that is supposed to send a repayment, you don’t want to repayment twice if the user clicks the button twice. Idempotency is a way to make sure that the action is only executed once. @@ -19,7 +17,7 @@ If no idempotency key is assigned to the request, the system will generate one f 2. The system checks there are already executed commands with the same `idempotency key` and `action name` and `entity name` 3. The action based on the result of the check * If the request is completed the system return with the already generated result - * If not completed, return HTTP 409 response + * If not completed, return HTTP 425 response, so the caller knows to come back rather than that something went wrong * If the request is not completed, we process the requests and store the results in the database @@ -34,5 +32,110 @@ In batch requests, you can set the idempotency key for every batch item, in the == Result of the request * When the request is already executed and completed, the system will return a `x-served-from-cache` header with the value `true` in the response and return the original request body. -* When the request is already executed but still not completed, the system will return to HTTP 409 error code +* When the request is already executed but still not completed, the system will return a HTTP 425 Too Early error code * When the request is not executed, the system runs it normally and stores the result in the date + + +== Idempotency in the new command processing + +The new command processing implements idempotency as command hooks, in the `fineract-command-idempotency` module. +It answers a repeated request the same way the legacy processing does - the same `x-served-from-cache` header, the +same `425 Too Early` while the original is still running, the same status and body once it has finished - with one +deliberate difference described under <>. + +=== Configuration + +Idempotency is on as soon as the module is on the classpath; a repeated request quietly executing twice should be a +decision rather than the consequence of an unset property. + +[source,properties] +---- +fineract.command.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true +---- + +The key is read from the HTTP header only. It is deliberately not read from a query parameter, because keys in query +strings are copied into access and proxy logs. + +=== How it works + +1. The key is taken from the request header. +2. The command is written to the command store immediately, before it is executed, claiming the key. The claim relies + on a unique constraint, so of several requests arriving at once with the same key exactly one wins and the others + are answered from the store. The command itself can never run twice. +3. The command runs, and the result it produces is stored against the claimed row by the audit hooks. A command that + produces no result of its own - one that failed, whose answer is rendered from an exception - has the answer the + client was sent recorded instead. See <>. + +=== What a repeat is answered from + +A completed command is replayed from the result object it produced. The stored result is read back into the object it +was and handed to the web layer, which renders it with the same serializer that rendered the original answer and +derives the same status code from it. The two answers are identical because they are the same object rendered the same +way, so nothing about the original response has to have been recorded - neither its bytes nor its status. + +A command that produced no result of its own has nothing to hand back. That is the case for a failure, whose answer is +rendered from an exception rather than from a result, and it is the only case where the answer itself is recorded: the +response as it went out, together with the status code it went out with, because a replay of it is thrown rather than +returned and nothing else could say what status to use. `response_status_code` is therefore set for those commands and +empty for every other. + +NOTE: Only a JSON answer can be recorded, because the column holds JSON. An answer of any other kind - a file download, +an empty body - is logged instead of stored, and a repeat of that key is answered with the status and an empty body. + +=== Result of a repeated request + +Every answer served from the command store carries `x-served-from-cache: true`, and no further command record is +written for it: the record that owns the key already describes the command, and a second one would claim an execution +that never happened. + +[cols="1,3"] +|=== +| State of the original command | Answer to the repeat + +| Completed +| The original status code and body. + +| Failed +| The original status code and body, so a repeat of a failure fails exactly as the original did. + +| Still being processed +| `425 Too Early`. The original has not finished, so there is nothing to replay yet and the caller should retry. + +| Completed, but its stored result cannot be reconstructed +| `409 Conflict`, saying so. The key has been used and its answer can no longer be produced - reporting a server error +would say the request failed, and an empty body would say it succeeded with nothing to return. Neither is true. + +| Any other state, or a key used for a different request +| `409 Conflict`. +|=== + +=== Scope of an idempotency key + +An idempotency key is unique per tenant across all commands. + +IMPORTANT: This differs from the legacy command processing, where a key is scoped by action and entity name, so the +same key could be used on two different endpoints. Under the new processing the second of those requests is rejected +with `409 Conflict` rather than executed. Clients that derive the key from something reused across calls, such as a +correlation id, have to send a distinct key per request. + +A repeat is also only replayed when it carries the same request as the original. A key reused for the same endpoint +with a different body is rejected with `409 Conflict` instead of being answered with the earlier result, which would +otherwise report success for something that was never carried out. + +=== Requires auditing + +Claiming a key writes the command record, but the idempotency hooks never write it again: it is the audit hooks that +move a command out of `UNDER_PROCESSING` and store what it produced. Idempotency therefore cannot work without +auditing, and an application configured with idempotency enabled and `fineract.command.audit.enabled=false` refuses to +start rather than failing later in a way that only shows up on a client's second request. + +See the command auditing chapter for what is recorded and when. + +=== Reliability + +Every write to the command record is retried - claiming the key, recording how the command finished, recording a +repeat, and recording an answer. A claim that loses to contention is tried again; a claim that loses to the unique +constraint is not, because that is the answer rather than a failure, and it means another request already owns the key. diff --git a/fineract-doc/src/docs/en/chapters/architecture/index.adoc b/fineract-doc/src/docs/en/chapters/architecture/index.adoc index 3ef38dbed7e..99448b1af90 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/index.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/index.adoc @@ -18,6 +18,8 @@ include::design.adoc[leveloffset=+1] include::persistence.adoc[leveloffset=+1] +include::command-audit.adoc[leveloffset=+1] + include::idempotency.adoc[leveloffset=+1] include::validation.adoc[leveloffset=+1] From feb9f2f3bb5a0d975012af33c1b6f5f8e23b8f5d Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 14:39:33 +0000 Subject: [PATCH 07/11] FINERACT-2485: Refuse a repeat whose claim never finished A command is recorded as UNDER_PROCESSING from the moment its key is claimed until the audit hooks record how it finished. If nothing ever does - the process dies in between, or the store gives up writing the row after its retries - the row stays that way for good, and answering 425 Too Early to every repeat tells the caller to come back for an answer that is never coming. A caller following the documented advice then retries for ever. Past fineract.command.idempotency.claim-timeout such a claim is treated as abandoned and the repeat is refused with 409, saying why. Age is the only signal available: nothing in the row distinguishes a command that died from one that is merely slow, so the default is generous and the setting is documented as one to widen rather than tighten. The key is refused, not released. The command that claimed it may have reached the database before whatever stopped it, so running it again is the duplicate this mechanism exists to prevent; establishing whether it took effect is a separate matter, and a retry needs a new key. No schema change: created_at is written when the key is claimed, and the audit hooks only ever touch updated_at and executed_at. --- .../IdempotencyCommandProperties.java | 14 ++++++ .../hook/IdempotencyCheckCommandHook.java | 43 +++++++++++++++++++ .../hook/IdempotencyCheckCommandHookTest.java | 42 +++++++++++++++--- .../command/jdbc/store/JdbcCommandStore.java | 7 +-- .../command/jdbc/JdbcCommandStoreTest.java | 1 + .../fineract/command/core/CommandReplay.java | 6 ++- .../en/chapters/architecture/idempotency.adoc | 22 +++++++++- .../src/main/resources/application.properties | 5 +++ 8 files changed, 128 insertions(+), 12 deletions(-) diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java index 1b57c80acb2..191cc4b8cf6 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java @@ -22,6 +22,7 @@ import java.io.Serial; import java.io.Serializable; +import java.time.Duration; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; @@ -57,4 +58,17 @@ public final class IdempotencyCommandProperties implements Serializable { @Builder.Default private String keyHeaderName = "Idempotency-Key"; + + /** + * How long a claimed command may stay unfinished before a repeat of its key is told the original will never + * complete, rather than being told to come back later. + * + *

+ * A claim that is never resolved - the process died between claiming the key and recording the outcome, or the + * store gave up after its retries - would otherwise answer every repeat {@code 425 Too Early} for ever, and a + * client following that advice retries for ever. Long enough that a slow command is not declared dead: the key is + * never re-executed, but a repeat past this point is refused, and the caller has to use a new one. + */ + @Builder.Default + private Duration claimTimeout = Duration.ofMinutes(10); } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java index 6f5aaaa259a..8ab57b85bb5 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -26,6 +26,7 @@ import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; +import java.time.Instant; import java.util.Map; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; @@ -38,6 +39,7 @@ import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; import org.apache.fineract.command.util.ServletHeaderUtil; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -54,6 +56,8 @@ final class IdempotencyCheckCommandHook implements CommandHookBefore ctx) { var command = ctx.getCommand(); @@ -81,6 +85,10 @@ public void onBefore(CommandContext ctx) { command.getInitiatedByUsername(), command.getIpAddress()); if (UNDER_PROCESSING.equals(replay.state())) { + if (abandoned(replay)) { + throw abandonedClaim(key, replay); + } + // the original has not finished, so there is nothing to replay yet and retrying is the right thing to do throw new CommandIdempotencyInProgressException(key, replay.response()); } @@ -127,6 +135,41 @@ private CommandReplay replayFor(String key) { } } + /** + * Whether a claim has been unfinished for longer than any command should take. + * + *

+ * A command that is recorded as running has either not finished yet or never will: the process died between + * claiming the key and recording the outcome, or the store gave up writing it. Nothing distinguishes the two from + * the row, so age stands in for it. Treated as abandoned only well past the point where a command could still be + * working, because the cost of being wrong is telling a caller their request failed while it is still running. + */ + private boolean abandoned(CommandReplay replay) { + var claimedAt = replay.claimedAt(); + + return claimedAt != null && claimedAt.isBefore(Instant.now().minus(properties.getClaimTimeout())); + } + + /** + * Refuses a repeat whose original will never finish. + * + *

+ * The alternative - answering {@code 425 Too Early} as for a command that is genuinely still running - tells the + * caller to come back, and nothing will ever change, so they retry for ever. The key is deliberately not released + * for another attempt: the first command may have reached the database before whatever stopped it, and running it + * again is the duplicate this whole mechanism exists to prevent. + */ + private CommandIdempotencyConflictException abandonedClaim(String key, CommandReplay replay) { + log.error("Idempotency key {} has been under processing since {}, longer than the {} it is given; the command that " + + "claimed it never recorded an outcome", key, replay.claimedAt(), properties.getClaimTimeout()); + + return new CommandIdempotencyConflictException(key, + Map.of("idempotencyKey", key, "error", + "The command that claimed this idempotency key never finished, so its answer cannot be produced and the " + + "key cannot be reused. Whether it took effect has to be established before retrying, and a " + + "retry needs a new idempotency key.")); + } + /** * Answers a repeat of a command that completed. * diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java index 7be76463cd0..421f77024c0 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -34,6 +34,8 @@ import static org.mockito.Mockito.verifyNoInteractions; import static org.mockito.Mockito.when; +import java.time.Duration; +import java.time.Instant; import java.util.Map; import org.apache.fineract.command.core.Command; import org.apache.fineract.command.core.CommandContext; @@ -43,6 +45,7 @@ import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; @@ -61,7 +64,7 @@ class IdempotencyCheckCommandHookTest { @BeforeEach void setUp() { - hook = new IdempotencyCheckCommandHook(store); + hook = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build()); } @Test @@ -90,7 +93,7 @@ void winningTheClaimLetsTheCommandExecute() { void anUnfinishedCommandAnswersTooEarly() { var ctx = context(KEY); - duplicate(new CommandReplay(UNDER_PROCESSING, null, null)); + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now())); var exception = assertThrows(CommandIdempotencyInProgressException.class, () -> hook.onBefore(ctx)); @@ -106,7 +109,7 @@ void aProcessedCommandIsReplayedByHandingBackItsOwnResult() { var stored = Map.of("resourceId", 7); - duplicate(new CommandReplay(PROCESSED, null, stored)); + duplicate(new CommandReplay(PROCESSED, null, stored, Instant.now())); when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); hook.onBefore(ctx); @@ -123,7 +126,7 @@ void aProcessedCommandWithOnlyACapturedAnswerIsThrownWithItsRecordedStatus() { // no result object to hand back, so the answer captured as it went out is replayed as the text it is, and // the status has to come from the record because nothing else can derive it - duplicate(new CommandReplay(PROCESSED, 201, "{\"resourceId\":7}")); + duplicate(new CommandReplay(PROCESSED, 201, "{\"resourceId\":7}", Instant.now())); when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); var exception = assertThrows(CommandIdempotencyProcessedException.class, () -> hook.onBefore(ctx)); @@ -138,7 +141,7 @@ void aFailedCommandIsReplayedAsTheSameFailure() { var stored = Map.of("error", "bad request"); - duplicate(new CommandReplay(ERROR, 400, stored)); + duplicate(new CommandReplay(ERROR, 400, stored, Instant.now())); when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); // this is what the old processing does: a repeat of a failure fails identically rather than being retried @@ -153,7 +156,7 @@ void aFailedCommandIsReplayedAsTheSameFailure() { void aKeyReusedForADifferentRequestConflicts() { var ctx = context(KEY); - duplicate(new CommandReplay(PROCESSED, 200, Map.of())); + duplicate(new CommandReplay(PROCESSED, 200, Map.of(), Instant.now())); when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(false); var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); @@ -165,7 +168,7 @@ void aKeyReusedForADifferentRequestConflicts() { void anUnrecognisedStateConflictsRatherThanGuessing() { var ctx = context(KEY); - duplicate(new CommandReplay(UNKNOWN, null, null)); + duplicate(new CommandReplay(UNKNOWN, null, null, Instant.now())); when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); @@ -186,6 +189,31 @@ void aStoredResultThatCannotBeReconstructedIsRefusedRatherThanGuessedAt() { "The answer must say what went wrong rather than coming back empty."); } + @Test + void aClaimThatNeverFinishedIsRefusedRatherThanAskedToRetryForEver() { + var ctx = context(KEY); + + // claimed well past the timeout and still recorded as running: the command that claimed it never came back + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofHours(1)))); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), + "425 would tell the caller to come back, and nothing will ever change, so they would retry for ever."); + assertTrue(String.valueOf(exception.getResponse()).contains("never finished"), + "The answer has to say why the key is unusable, or a caller cannot tell it from a transient 409."); + } + + @Test + void aClaimThatIsStillWithinItsTimeIsToldToComeBack() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofMinutes(1)))); + + assertThrows(CommandIdempotencyInProgressException.class, () -> hook.onBefore(ctx), + "A command that could still be running must not be declared dead."); + } + private void duplicate(CommandReplay replay) { when(store.claim(any())).thenReturn(false); when(store.getReplayByKey(KEY)).thenReturn(replay); diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java index 3bd2f575833..b96a79590eb 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java @@ -78,9 +78,10 @@ public boolean existsByKey(String key) { @Override public CommandReplay getReplayByKey(String key) { - return repository.findOneByIdempotencyKey(key).map( - entity -> new CommandReplay(entity.getState(), entity.getResponseStatusCode(), replayResponse(key, entity.getResponse()))) - .orElseGet(() -> new CommandReplay(UNKNOWN, null, null)); + return repository.findOneByIdempotencyKey(key) + .map(entity -> new CommandReplay(entity.getState(), entity.getResponseStatusCode(), + replayResponse(key, entity.getResponse()), entity.getCreatedAt())) + .orElseGet(() -> new CommandReplay(UNKNOWN, null, null, null)); } /** diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java index 9dd0e0cc76f..33a7716d715 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -214,6 +214,7 @@ public void theStateOfAKeyTellsAnInFlightCommandFromAFinishedOne() { var inFlight = store.getReplayByKey(key); assertEquals(UNDER_PROCESSING, inFlight.state(), "A claimed key should report the command as in flight."); + assertNotNull(inFlight.claimedAt(), "When the key was claimed is what tells a slow command from an abandoned one."); assertNull(inFlight.statusCode(), "An in-flight command has not been answered yet."); assertNull(inFlight.response(), "An in-flight command has nothing to replay."); diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java index 1840b5b391c..1f43fcf8c57 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.core; +import java.time.Instant; + /** * What is known about a command already stored under an idempotency key: enough to answer a repeated request exactly as * the original one was answered, without executing anything. @@ -26,10 +28,12 @@ * the state the stored command is in * @param statusCode * the HTTP status the original request was answered with, {@code null} if it never completed + * @param claimedAt + * when the command was claimed, used to tell a command that is still running from one that never finished * @param response * the response object the original command produced, rehydrated from the command store, {@code null} if it * never completed. It is handed back to the web layer as an object rather than as text so that the same * serializer that rendered the original answer renders the replay, which is what makes the two identical. */ -public record CommandReplay(CommandState state, Integer statusCode, Object response) { +public record CommandReplay(CommandState state, Integer statusCode, Object response, Instant claimedAt) { } diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index d0b0f95313c..95f35885101 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -54,6 +54,7 @@ fineract.command.idempotency.enabled=true fineract.command.idempotency.key-header-name=Idempotency-Key fineract.command.idempotency.hook-key-header-pre=true fineract.command.idempotency.hook-check-pre=true +fineract.command.idempotency.claim-timeout=10m ---- The key is read from the HTTP header only. It is deliberately not read from a query parameter, because keys in query @@ -101,9 +102,12 @@ that never happened. | Failed | The original status code and body, so a repeat of a failure fails exactly as the original did. -| Still being processed +| Still being processed, claimed within `claim-timeout` | `425 Too Early`. The original has not finished, so there is nothing to replay yet and the caller should retry. +| Still being processed, claimed longer ago than `claim-timeout` +| `409 Conflict`, saying the command never finished. See <>. + | Completed, but its stored result cannot be reconstructed | `409 Conflict`, saying so. The key has been used and its answer can no longer be produced - reporting a server error would say the request failed, and an empty body would say it succeeded with nothing to return. Neither is true. @@ -139,3 +143,19 @@ See the command auditing chapter for what is recorded and when. Every write to the command record is retried - claiming the key, recording how the command finished, recording a repeat, and recording an answer. A claim that loses to contention is tried again; a claim that loses to the unique constraint is not, because that is the answer rather than a failure, and it means another request already owns the key. + +=== A claim that never finishes + +A command is recorded as `UNDER_PROCESSING` from the moment its key is claimed until the audit hooks record how it +finished. If nothing ever records that - the process dies in between, or the store gives up writing the row after its +retries - the row stays `UNDER_PROCESSING` for good. Answering `425 Too Early` to every repeat would then tell the +caller to come back for an answer that is never coming, and a caller following that advice retries for ever. + +Past `fineract.command.idempotency.claim-timeout`, such a claim is treated as abandoned and a repeat is refused with +`409 Conflict` instead. Nothing distinguishes a command that died from one that is merely slow, so age stands in for +it: set the timeout comfortably above the slowest command rather than tightly, because the cost of being wrong is +telling a caller their request failed while it is still running. + +IMPORTANT: The key is refused, not released. The command that claimed it may have reached the database before whatever +stopped it, so running it again is exactly the duplicate this mechanism exists to prevent. Whether the original took +effect has to be established some other way, and a retry needs a new idempotency key. diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index fdde5a1a1ed..eb17c3c3237 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -955,6 +955,11 @@ fineract.command.idempotency.enabled=${FINERACT_COMMAND_IDEMPOTENCY_ENABLED:true fineract.command.idempotency.key-header-name=${FINERACT_IDEMPOTENCY_KEY_HEADER_NAME:Idempotency-Key} fineract.command.idempotency.hook-key-header-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_KEY_HEADER_PRE:true} fineract.command.idempotency.hook-check-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_CHECK_PRE:true} +# How long a claimed command may stay unfinished before a repeat of its key is refused rather than told to retry. +# Guards against a claim that is never resolved - the process died before recording the outcome - which would +# otherwise answer 425 for ever. The key is never re-executed, only refused, so set it comfortably above the +# slowest command rather than tightly. +fineract.command.idempotency.claim-timeout=${FINERACT_COMMAND_IDEMPOTENCY_CLAIM_TIMEOUT:10m} # Fineract Default Config values fineract.defaults.office-id=${FINERACT_CONFIG_DEFAULT_OFFICE_ID:1} From 84e63fea6827485b4a3320a213c3093bc3b983a2 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 16:24:32 +0000 Subject: [PATCH 08/11] FINERACT-2485: Record what a command acted on and what it did m_command carries approved_at and approved_by_username but nothing that says which entity and action a command concerns, so the approval columns cannot be used: maker-checker derives the permission governing approval by joining the two names with _CHECKER, the way the legacy processing does. The audit search and the checker inbox are defined in the same terms - the inbox returns the actionNames and entityNames a requestor may approve - so a row without them is invisible to both. This adds entity_name and action_name, and the means of filling them. Declared as abstract methods on Command rather than an optional interface. The interface shape is what left 44 of 47 commands without names; a command that forgets them would be stored with none, and a row no audit or inbox can find is worse than a compile error. The columns are therefore NOT NULL, with rows written before the change backfilled as UNKNOWN. The names are the ones in m_permission, checked against the 953 pairs the seed data defines, and they are not always what the class name suggests: CacheSwitchCommand is CACHE/UPDATE, the entity is BUSINESS_DATE rather than BUSINESSDATE, collateral is COLLATERAL_PRODUCT and CLIENT_COLLATERAL_PRODUCT, chart slabs are CHARTSLAB, and attendance is an action on MEETING. Notes and images act on different entities depending on the request - a note belongs to whatever it is attached to, an image to a client or a member of staff - so those compute the name from the payload, which is set before the command is stored. Two consequences worth naming. HookableCommand loses its two methods and becomes a marker: they duplicated what every command now declares, and it only ever meant "notify webhooks". And an abstract Command cannot be the target of the mapper's read direction, so a row read back becomes a StoredCommand carrying the recorded names - there is no class left to ask. The migration test rolls back a fixed number of changesets, which has to grow with every part added after 0003, or it leaves the unique constraint in place and the re-seed collides. --- .../hook/IdempotencyCheckCommandHookTest.java | 16 ++++- .../jdbc/store/domain/CommandEntity.java | 6 ++ .../jdbc/store/domain/StoredCommand.java | 50 ++++++++++++++ .../jdbc/store/mapping/JdbcCommandMapper.java | 11 +++- .../command/module-changelog-master.xml | 1 + .../parts/0005_command_action_entity.xml | 65 +++++++++++++++++++ .../CommandIdempotencyKeyMigrationTest.java | 7 +- .../jdbc/JdbcCommandStoreRetryTest.java | 16 ++++- .../command/jdbc/JdbcCommandStoreTest.java | 14 ++++ .../command-migration-test-changelog.xml | 1 + .../test/sample/command/DummyCommand.java | 13 +++- .../sample/command/DummyErrorCommand.java | 13 +++- .../apache/fineract/command/core/Command.java | 19 +++++- .../command/core/HookableCommand.java | 15 ++--- .../command/BusinessDateUpdateCommand.java | 13 +++- .../cache/command/CacheSwitchCommand.java | 13 +++- .../ExternalConfigurationsUpdateCommand.java | 13 +++- .../command/WebhookCommandEventPublisher.java | 12 ++-- .../command/WebhookCommandHookAfter.java | 6 +- .../command/WebhookCommandHookError.java | 4 +- .../command/CurrencyUpdateCommand.java | 13 +++- .../command/PaymentTypeCreateCommand.java | 13 +++- .../command/PaymentTypeDeleteCommand.java | 13 +++- .../command/PaymentTypeUpdateCommand.java | 13 +++- .../command/WebhookCommandHookAfterTest.java | 20 +++++- .../command/WebhookCommandHookErrorTest.java | 20 +++++- .../chapters/architecture/command-audit.adoc | 26 ++++++++ .../command/DocumentCreateCommand.java | 4 +- .../command/DocumentDeleteCommand.java | 4 +- .../command/DocumentUpdateCommand.java | 4 +- .../command/ImageCreateCommand.java | 14 +++- .../command/ImageDeleteCommand.java | 14 +++- .../hooks/command/HookCreateCommand.java | 13 +++- .../hooks/command/HookDeleteCommand.java | 13 +++- .../hooks/command/HookUpdateCommand.java | 13 +++- .../staff/command/StaffCreateCommand.java | 13 +++- .../staff/command/StaffUpdateCommand.java | 13 +++- .../staff/command/StaffUploadCommand.java | 13 +++- .../command/WorkingDaysUpdateCommand.java | 13 +++- .../ClientCollateralCreateCommand.java | 13 +++- .../ClientCollateralDeleteCommand.java | 13 +++- .../ClientCollateralUpdateCommand.java | 13 +++- .../CollateralProductCreateCommand.java | 13 +++- .../CollateralProductDeleteCommand.java | 13 +++- .../CollateralProductUpdateCommand.java | 13 +++- .../command/LoanCollateralDeleteCommand.java | 13 +++- .../InterestRateChartCreateCommand.java | 13 +++- .../InterestRateChartDeleteCommand.java | 13 +++- .../InterestRateChartSlabsCreateCommand.java | 13 +++- .../InterestRateChartSlabsDeleteCommand.java | 13 +++- .../InterestRateChartSlabsUpdateCommand.java | 13 +++- .../InterestRateChartUpdateCommand.java | 13 +++- .../command/ProductMixCreateCommand.java | 13 +++- .../command/ProductMixDeleteCommand.java | 13 +++- .../command/ProductMixUpdateCommand.java | 13 +++- .../MeetingAttendanceUpdateCommand.java | 13 +++- .../meeting/command/MeetingCreateCommand.java | 13 +++- .../meeting/command/MeetingDeleteCommand.java | 13 +++- .../meeting/command/MeetingUpdateCommand.java | 13 +++- .../note/command/NoteCreateCommand.java | 21 +++++- .../note/command/NoteDeleteCommand.java | 21 +++++- .../note/command/NoteUpdateCommand.java | 21 +++++- .../command/TemplateCreateCommand.java | 13 +++- .../command/TemplateDeleteCommand.java | 13 +++- .../command/TemplateUpdateCommand.java | 13 +++- .../command/FloatingRateCreateCommand.java | 13 +++- .../command/FloatingRateUpdateCommand.java | 13 +++- 67 files changed, 859 insertions(+), 86 deletions(-) create mode 100644 fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java index 421f77024c0..8b52b430c99 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -220,11 +220,25 @@ private void duplicate(CommandReplay replay) { } private static CommandContext context(String key) { - var command = new Command(); + var command = new TestCommand(); command.setIdempotencyKey(key); command.setPayload("request-payload"); return CommandContext.builder().command(command).build(); } + + /** Commands declare their names in code; a test fixture has to as well. */ + private static final class TestCommand extends Command { + + @Override + public String entityName() { + return "DOCUMENT"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } } diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java index 8768134325a..2e4573d19b0 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java @@ -72,6 +72,12 @@ public class CommandEntity implements Serializable { @Column("rejected_by_username") private String rejectedByUsername; + @Column("entity_name") + private String entityName; + + @Column("action_name") + private String actionName; + @Column("idempotency_key") private String idempotencyKey; diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java new file mode 100644 index 00000000000..0c070ceb56e --- /dev/null +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java @@ -0,0 +1,50 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc.store.domain; + +import lombok.Data; +import lombok.EqualsAndHashCode; +import org.apache.fineract.command.core.Command; + +/** + * A command read back out of the command table. + * + *

+ * Every command declares its entity and action in code, which is what makes them impossible to forget. A command + * reconstructed from a stored row has no code to ask - the class that declared them is not involved - so it carries the + * names that were recorded with it instead. + */ +@Data +@EqualsAndHashCode(callSuper = true) +public class StoredCommand extends Command { + + private String entityName; + + private String actionName; + + @Override + public String entityName() { + return entityName; + } + + @Override + public String actionName() { + return actionName; + } +} diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java index 9a4fe19e585..1a47c3eb6db 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java @@ -23,7 +23,7 @@ import org.apache.fineract.command.core.Command; import org.apache.fineract.command.jdbc.store.domain.CommandEntity; -import org.mapstruct.InheritInverseConfiguration; +import org.apache.fineract.command.jdbc.store.domain.StoredCommand; import org.mapstruct.Mapper; import org.mapstruct.Mapping; @@ -44,6 +44,8 @@ public interface JdbcCommandMapper { @Mapping(source = "ipAddress", target = "ipAddress") @Mapping(source = "idempotencyKey", target = "idempotencyKey") @Mapping(source = "error", target = "error") + @Mapping(expression = "java(source.entityName())", target = "entityName") + @Mapping(expression = "java(source.actionName())", target = "actionName") @Mapping(ignore = true, target = "state") @Mapping(ignore = true, target = "response") CommandEntity map(Command source); @@ -60,12 +62,15 @@ public interface JdbcCommandMapper { @Mapping(source = "source.rejectedByUsername", target = "rejectedByUsername") @Mapping(source = "source.payload", target = "request") @Mapping(source = "source.ipAddress", target = "ipAddress") + @Mapping(expression = "java(source.entityName())", target = "entityName") + @Mapping(expression = "java(source.actionName())", target = "actionName") @Mapping(source = "source.idempotencyKey", target = "idempotencyKey") @Mapping(source = "source.error", target = "error") @Mapping(source = "response", target = "response") @Mapping(ignore = true, target = "state") CommandEntity map(Command source, Object response); - @InheritInverseConfiguration - Command map(CommandEntity source); + @Mapping(source = "id", target = "commandId") + @Mapping(source = "request", target = "payload") + StoredCommand map(CommandEntity source); } diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml index a01e922530d..6992d1ee3d8 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml @@ -26,5 +26,6 @@ + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml new file mode 100644 index 00000000000..0063da529c1 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml @@ -0,0 +1,65 @@ + + + + + + + Which entity a command acts on and what it does to it, in the vocabulary of m_permission. Without them a + command record cannot be found by an audit search or a checker inbox, both of which are defined in terms + of these two names, and the permission governing maker-checker approval - the action and entity joined + with _CHECKER - cannot be derived. The approval columns are already on this table; this is what they need + to become usable. + + Not null, because a row without them is invisible to everything that reads this table by name. Rows that + predate this column are backfilled as UNKNOWN: they were written before commands recorded it, and saying + so is better than implying they acted on an entity called "". + + + + + + + + + + + diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java index 917df2f7f68..9e0ffd8dc12 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java @@ -141,12 +141,13 @@ private void migrate(JdbcDatabaseContainer container, String context) throws } /** - * Reverts the unique constraint, which means also reverting the response-cache changeset stacked on top of it. Both - * databases apply the same number of changesets from that point on. + * Reverts the unique constraint, which means also reverting the response-cache and action/entity changesets stacked + * on top of it. Both databases apply the same number of changesets from that point on, so this count has to grow + * with every part added after 0003. */ private void rollbackUniqueConstraint(JdbcDatabaseContainer container, String context) throws Exception { try (var connection = connect(container); var liquibase = liquibase(connection)) { - liquibase.rollback(2, new Contexts(context), new LabelExpression()); + liquibase.rollback(3, new Contexts(context), new LabelExpression()); } } diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java index 56508afaf38..2cb53d6388e 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java @@ -103,7 +103,7 @@ private static Throwable catchFailure(Runnable runnable) { } private static Command command() { - var command = new Command<>(); + var command = new TestCommand(); command.setIdempotencyKey("a-key"); @@ -119,4 +119,18 @@ CommandStore commandStore(JdbcCommandMapper mapper, JdbcCommandRepository reposi null); } } + + /** Commands declare their names in code; a test fixture has to as well. */ + private static final class TestCommand extends Command { + + @Override + public String entityName() { + return "DOCUMENT"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } } diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java index 33a7716d715..db94620fd37 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -296,6 +296,20 @@ public void storingTheCommandDoesNotResetTheRecordedStatus() { assertEquals(400, store.getReplayByKey(key).statusCode(), "A full-row save must not wipe the recorded status."); } + @Test + public void theCommandRecordsWhatItActedOnAndWhatItDid() { + var key = UUID.randomUUID().toString(); + + store.claim(command(key, "hello")); + + var claimed = repository.findOneByIdempotencyKey(key).orElseThrow(); + + // the names an audit search and a checker inbox look a command up by, and from which the approval permission + // is derived; a row without them is invisible to both + assertEquals("DUMMY", claimed.getEntityName(), "The entity the command acted on must be recorded."); + assertEquals("CREATE", claimed.getActionName(), "The action it performed must be recorded."); + } + private static CommandContext processed(String key, String content) { return CommandContext.builder().command(command(key, content)) .response(DummyResponse.builder().content(content.toUpperCase(Locale.ROOT)).build()).state(PROCESSED).build(); diff --git a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml index 1309ed964fb..e3cc0c19edd 100644 --- a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml +++ b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml @@ -72,5 +72,6 @@ + diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java index 14829a781da..25487893438 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class DummyCommand extends Command {} +public class DummyCommand extends Command { + + @Override + public String entityName() { + return "DUMMY"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java index 11e07ed0576..020637dde5c 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class DummyErrorCommand extends Command {} +public class DummyErrorCommand extends Command { + + @Override + public String entityName() { + return "DUMMY"; + } + + @Override + public String actionName() { + return "ERROR"; + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java index 8441f3ca620..db88938890e 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java @@ -26,7 +26,7 @@ @Data @FieldNameConstants -public class Command implements Serializable { +public abstract class Command implements Serializable { @Serial private static final long serialVersionUID = 1L; @@ -58,4 +58,21 @@ public class Command implements Serializable { private String error; private T payload; + + /** + * The entity this command acts on, in the vocabulary of {@code m_permission} - {@code DOCUMENT}, + * {@code BUSINESS_DATE}, {@code CLIENT_COLLATERAL_PRODUCT}. Recorded against the command so that it can be found in + * an audit and, once maker-checker reaches this framework, so that the permission governing its approval can be + * derived the way the legacy processing derives it. + * + *

+ * Abstract rather than defaulted on purpose: a command whose name is missing would be written with no entity, and a + * row that no checker inbox and no audit search can find is worse than a compile error. For a command that acts on + * different entities depending on its payload - a note, an image - this is computed from that payload, which is set + * before the command is stored. + */ + public abstract String entityName(); + + /** The action this command performs on {@link #entityName()}, again as {@code m_permission} spells it. */ + public abstract String actionName(); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java b/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java index 6af72daf36d..286b71e3784 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java @@ -20,12 +20,11 @@ /** * Implemented by commands whose successful execution must notify the webhooks registered for its event, as the legacy - * command processing does for every command. The names are the entity and action a hook subscribes to, e.g. - * {@code DOCUMENT} and {@code CREATE}. + * command processing does for every command. + * + *

+ * A marker only. The entity and action a hook subscribes to are {@link Command#entityName()} and + * {@link Command#actionName()}, which every command declares; this says nothing more than whether webhooks are notified + * for this one. */ -public interface HookableCommand { - - String hookEntityName(); - - String hookActionName(); -} +public interface HookableCommand {} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java index a85b362973e..11e9a2dcde0 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class BusinessDateUpdateCommand extends Command {} +public class BusinessDateUpdateCommand extends Command { + + @Override + public String entityName() { + return "BUSINESS_DATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java index a8a95889449..6b91aee79ae 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CacheSwitchCommand extends Command {} +public class CacheSwitchCommand extends Command { + + @Override + public String entityName() { + return "CACHE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java index c42d79b2ebe..b406ad8785b 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ExternalConfigurationsUpdateCommand extends Command {} +public class ExternalConfigurationsUpdateCommand extends Command { + + @Override + public String entityName() { + return "EXTERNAL_EVENT_CONFIGURATION"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java index 5d949c37f67..05fbd4d8269 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java @@ -25,7 +25,7 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.fineract.batch.exception.ErrorInfo; -import org.apache.fineract.command.core.HookableCommand; +import org.apache.fineract.command.core.Command; import org.apache.fineract.infrastructure.core.exception.ErrorHandler; import org.apache.fineract.infrastructure.core.service.ThreadLocalContextUtil; import org.apache.fineract.infrastructure.hooks.event.HookEvent; @@ -53,7 +53,7 @@ class WebhookCommandEventPublisher { private final ObjectMapper mapper; private final ErrorHandler errorHandler; - void publishSuccess(HookableCommand hookable, Object request, Object response) { + void publishSuccess(Command hookable, Object request, Object response) { publish(hookable, request, payload -> { // As in the legacy command processing, the office and client are exposed at the top level of the payload, // where the SMS hooks look up the client to notify, and the office is cleared from the response. @@ -69,7 +69,7 @@ void publishSuccess(HookableCommand hookable, Object request, Object response) { }); } - void publishError(HookableCommand hookable, Object request, Throwable error) { + void publishError(Command hookable, Object request, Throwable error) { publish(hookable, request, payload -> { final ErrorInfo errorInfo = errorHandler.handle(ErrorHandler.getMappable(error)); payload.put("status", "Exception"); @@ -77,9 +77,9 @@ void publishError(HookableCommand hookable, Object request, Throwable error) { }); } - private void publish(HookableCommand hookable, Object request, Consumer> result) { - final String entityName = hookable.hookEntityName(); - final String actionName = hookable.hookActionName(); + private void publish(Command hookable, Object request, Consumer> result) { + final String entityName = hookable.entityName(); + final String actionName = hookable.actionName(); try { final AppUser user = context.authenticatedUser(); diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java index 31da6d756db..2d1e574cc18 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java @@ -41,7 +41,7 @@ final class WebhookCommandHookAfter implements CommandHookAfter public void onAfter(CommandContext ctx) { var command = ctx.getCommand(); - if (!(command instanceof HookableCommand hookable)) { + if (!(command instanceof HookableCommand)) { return; } @@ -55,11 +55,11 @@ public void onAfter(CommandContext ctx) { @Override public void afterCommit() { - publisher.publishSuccess(hookable, command.getPayload(), response); + publisher.publishSuccess(command, command.getPayload(), response); } }); } else { - publisher.publishSuccess(hookable, command.getPayload(), response); + publisher.publishSuccess(command, command.getPayload(), response); } } } diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java index bc5877bf670..6cf9aec93c4 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java @@ -39,13 +39,13 @@ final class WebhookCommandHookError implements CommandHookError public void onError(CommandContext ctx) { var command = ctx.getCommand(); - if (!(command instanceof HookableCommand hookable)) { + if (!(command instanceof HookableCommand)) { return; } // Publish right away, as in the legacy command processing: when the handler fails, its work is rolled back, so // there is no commit to wait for. A hook can also fail after the handler has committed, e.g. when the audit // hook can't store the command. The event then reports the error the API returns, for a change that was saved. - publisher.publishError(hookable, command.getPayload(), ctx.getError()); + publisher.publishError(command, command.getPayload(), ctx.getError()); } } diff --git a/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java index b93083edd0c..7d08b0f36a8 100644 --- a/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CurrencyUpdateCommand extends Command {} +public class CurrencyUpdateCommand extends Command { + + @Override + public String entityName() { + return "CURRENCY"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java index dc6d98a7669..c78afc865f0 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeCreateCommand extends Command {} +public class PaymentTypeCreateCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java index dc251e713ba..49dfd60d02c 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeDeleteCommand extends Command {} +public class PaymentTypeDeleteCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java index 48fdf2b6182..fe60793bbb6 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeUpdateCommand extends Command {} +public class PaymentTypeUpdateCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java index 55fe6aa322a..7fab6659a80 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java @@ -126,7 +126,7 @@ void shouldExposeOfficeAndClientAtTopLevelOfPayload() { @Test void shouldIgnoreCommandThatIsNotHookable() { - final Command command = new Command<>(); + final Command command = new TestPlainCommand(); command.setPayload(new TestRequest("contract.pdf", null)); underTest.onAfter(afterContext(command, new TestResponse(7L))); @@ -166,15 +166,29 @@ private static Command hookableCommand() { return command; } + /** A command that notifies no webhooks, to check that it is left alone. */ + private static final class TestPlainCommand extends Command { + + @Override + public String entityName() { + return "DOCUMENT"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } + private static final class TestHookableCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "CREATE"; } } diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java index ab4a4038e8e..4b9a24d0430 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java @@ -146,7 +146,7 @@ void shouldPublishImmediatelyInsideEnclosingTransaction() { @Test void shouldIgnoreCommandThatIsNotHookable() { - final Command command = new Command<>(); + final Command command = new TestPlainCommand(); command.setPayload(new TestRequest("contract.pdf", null)); underTest.onError(errorContext(command, new IllegalStateException("not found"))); @@ -182,15 +182,29 @@ private static Command hookableCommand() { return command; } + /** A command that notifies no webhooks, to check that it is left alone. */ + private static final class TestPlainCommand extends Command { + + @Override + public String entityName() { + return "DOCUMENT"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } + private static final class TestHookableCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "DELETE"; } } diff --git a/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc index 895beca27c9..4545d825376 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc @@ -49,6 +49,10 @@ execution that never happened. |=== | Column | Content +| `entity_name`, `action_name` +| What the command acted on and what it did, in the vocabulary of `m_permission` - `DOCUMENT`/`CREATE`, +`BUSINESS_DATE`/`UPDATE`. See <>. + | `state` | `UNDER_PROCESSING`, `PROCESSED` or `ERROR`. `UNKNOWN` is reported for a key that has no record at all. @@ -96,6 +100,28 @@ If the writes still fail after their attempts are spent, the command itself is u processed and answered. A record that could not be written is logged, and, when the dead-letter queue is enabled, the command is written to it so that the trail can be reconstructed. +== Why the names are mandatory + +`Command` declares `entityName()` and `actionName()` as abstract methods, so a command cannot be written without +saying what it acts on. That is deliberate rather than convenient. + +Both names are read by position, not by meaning: the audit search and the checker inbox are defined in terms of them - +the inbox returns "the `actionNames` and `entityNames` the requestor has Checker approval permissions for" - and +maker-checker derives the permission that governs approval by joining them with `_CHECKER`, the way +`PortfolioCommandSourceWritePlatformServiceImpl` does for the legacy processing. The approval columns are already on +this table. A command whose names were missing would be stored with none of that, and would simply not appear in +either view: no error, no failing test, just a row nobody can find. Hence abstract methods and `NOT NULL` columns +rather than an optional interface. + +The names have to match the vocabulary already in `m_permission`, which is not always what the class name suggests - +`CacheSwitchCommand` is `CACHE`/`UPDATE`, not `CACHE`/`SWITCH`, and the entity is `BUSINESS_DATE` rather than +`BUSINESSDATE`. A few commands act on different entities depending on their payload: a note belongs to whatever it is +attached to (`CLIENTNOTE`, `LOANNOTE`, ...) and an image to either `CLIENTIMAGE` or `STAFFIMAGE`, so those compute the +name from the request rather than returning a constant. + +NOTE: Rows written before this column existed are backfilled as `UNKNOWN`. They were recorded when commands did not +carry the names, and saying so is more honest than implying they acted on an entity with an empty name. + == Relationship with idempotency The audit hooks own the lifecycle of the command record. Idempotency claims the key and counts repeats, but it is the diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java index face5244f81..6e6f75f9683 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java @@ -29,12 +29,12 @@ public class DocumentCreateCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "CREATE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java index ed94119436c..b171d59c900 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java @@ -29,12 +29,12 @@ public class DocumentDeleteCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "DELETE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java index d0c1c7c1b19..a0aba017169 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java @@ -29,12 +29,12 @@ public class DocumentUpdateCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "UPDATE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java index 2018da75e22..b49730471d1 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java @@ -25,4 +25,16 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ImageCreateCommand extends Command {} +public class ImageCreateCommand extends Command { + + /** {@code clients} and {@code staff} are separate permissions, so the entity follows what the request targets. */ + @Override + public String entityName() { + return "staff".equalsIgnoreCase(getPayload().getEntityType()) ? "STAFFIMAGE" : "CLIENTIMAGE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java index e510df6607c..cb7aae60918 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java @@ -25,4 +25,16 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ImageDeleteCommand extends Command {} +public class ImageDeleteCommand extends Command { + + /** {@code clients} and {@code staff} are separate permissions, so the entity follows what the request targets. */ + @Override + public String entityName() { + return "staff".equalsIgnoreCase(getPayload().getEntityType()) ? "STAFFIMAGE" : "CLIENTIMAGE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java index a7c50a88cf8..fd3f12b83c6 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookCreateCommand extends Command {} +public class HookCreateCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java index fe3ce311d9a..043a4d93a0a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookDeleteCommand extends Command {} +public class HookDeleteCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java index 762135f777f..6773b1c30a0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookUpdateCommand extends Command {} +public class HookUpdateCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java index be114d1164d..f0188e21f97 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffCreateCommand extends Command {} +public class StaffCreateCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java index 62cb6557753..d58cfbf3a4e 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffUpdateCommand extends Command {} +public class StaffUpdateCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java index 20ce42e06e2..e4790b6f477 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffUploadCommand extends Command {} +public class StaffUploadCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java index d9fb6693165..8deae856725 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class WorkingDaysUpdateCommand extends Command {} +public class WorkingDaysUpdateCommand extends Command { + + @Override + public String entityName() { + return "WORKINGDAYS"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java index a4cb599276a..20246624114 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralCreateCommand extends Command {} +public class ClientCollateralCreateCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java index eba27f6e03b..2ce0e8455bc 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralDeleteCommand extends Command {} +public class ClientCollateralDeleteCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java index feb29e65491..6eaf24a64ba 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralUpdateCommand extends Command {} +public class ClientCollateralUpdateCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java index 1adf4b6179e..bf40a5f07ee 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductCreateCommand extends Command {} +public class CollateralProductCreateCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java index 1d6fa91e5c9..4258ef4b3a9 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductDeleteCommand extends Command {} +public class CollateralProductDeleteCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java index facbeba45ea..ef1b22fea84 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductUpdateCommand extends Command {} +public class CollateralProductUpdateCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java index f592c359fff..9fee66bf235 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class LoanCollateralDeleteCommand extends Command {} +public class LoanCollateralDeleteCommand extends Command { + + @Override + public String entityName() { + return "LOAN_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java index a0a72c6168d..a6c9cdd2ced 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartCreateCommand extends Command {} +public class InterestRateChartCreateCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java index 1486c0a6f84..6763673ba09 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartDeleteCommand extends Command {} +public class InterestRateChartDeleteCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java index 5b3cdde0057..47f75a1a89a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsCreateCommand extends Command {} +public class InterestRateChartSlabsCreateCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java index fb62d9f9c50..36fd33e05c0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsDeleteCommand extends Command {} +public class InterestRateChartSlabsDeleteCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java index 5d4905b8684..403593e462e 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsUpdateCommand extends Command {} +public class InterestRateChartSlabsUpdateCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java index ceab67450b8..efb3c3bc838 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartUpdateCommand extends Command {} +public class InterestRateChartUpdateCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java index f64ab37fb1c..43a25d8dcb4 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixCreateCommand extends Command {} +public class ProductMixCreateCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java index b5174548afd..04319d9fc8f 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixDeleteCommand extends Command {} +public class ProductMixDeleteCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java index c9c1241484f..d177f290ffd 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixUpdateCommand extends Command {} +public class ProductMixUpdateCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java index 2df5e965c39..b84d71f95f9 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingAttendanceUpdateCommand extends Command {} +public class MeetingAttendanceUpdateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "SAVEORUPDATEATTENDANCE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java index 69af8608c0c..f3b4718931d 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingCreateCommand extends Command {} +public class MeetingCreateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java index 861a13ede03..e3cb4904b52 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingDeleteCommand extends Command {} +public class MeetingDeleteCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java index 13cf54c743f..a2e46a6e86b 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingUpdateCommand extends Command {} +public class MeetingUpdateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java index 22061079144..1f21ec305f0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteCreateCommand extends Command {} +public class NoteCreateCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java index ba97ea2f6a4..4250030d343 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteDeleteCommand extends Command {} +public class NoteDeleteCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java index 2671bb2f92c..a126b8cf8c0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteUpdateCommand extends Command {} +public class NoteUpdateCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java index f4fd467dd7a..06780c079b3 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateCreateCommand extends Command {} +public class TemplateCreateCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java index 8d8f328c752..f7be73f4e4d 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateDeleteCommand extends Command {} +public class TemplateDeleteCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java index eecf7933c2a..bb420d05225 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateUpdateCommand extends Command {} +public class TemplateUpdateCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java index 0a75f1ef512..e763b552876 100644 --- a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java +++ b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class FloatingRateCreateCommand extends Command {} +public class FloatingRateCreateCommand extends Command { + + @Override + public String entityName() { + return "FLOATINGRATE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java index 944ecc0c0f0..98e4a319c67 100644 --- a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java +++ b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class FloatingRateUpdateCommand extends Command {} +public class FloatingRateUpdateCommand extends Command { + + @Override + public String entityName() { + return "FLOATINGRATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} From d714be78a6a916b237b190a40738b50e72175abb Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 17:53:14 +0000 Subject: [PATCH 09/11] FINERACT-2485: Scope idempotency keys with a distinctor and close replay gaps An idempotency key is now unique together with a distinctor, stored beside it in the new NOT NULL column m_command.custom_idempotency_distinctor (default ''). The composite unique constraint replaces the key-only one; it is added before the old one is dropped, so the key is never left unconstrained. The configured CustomIdempotencyDistinctor computes the value when the key is claimed: ENTITY_NAME_AND_ACTION_NAME (the default, e.g. LOAN|CREATE) scopes a key the way the legacy processing does, NONE makes it unique per tenant. Every lookup by key - claim, replay, request comparison, recorded response - also matches the distinctor, and IdempotencyKeyLookupCoverageTest fails the build on a lookup that does not. Review fixes on the same path: - Four collateral command results had no constructor Jackson could use, so a repeat of those requests was refused with 409 instead of replayed. They are now constructible, and CommandHandlerResultRehydrationTest reads every handler's result type back the way a replay does. The 409 for a result that cannot be rebuilt no longer invites a retry under a new key: the command did take effect. - Idempotency refuses to start with the audit after or error hook switched off, not only with auditing off: without them a command never leaves UNDER_PROCESSING. - A claim is always stored with its time, even with the timestamp hook off, so the claim timeout can tell an abandoned claim from a running one. --- .../IdempotencyCommandConstants.java | 4 + .../IdempotencyCommandProperties.java | 9 + .../IdempotencyCommandPropertyCheck.java | 21 ++ .../CustomIdempotencyDistinctor.java | 52 +++++ .../CustomIdempotencyDistinctorType.java | 44 ++++ ...ActionNameCustomIdempotencyDistinctor.java | 39 ++++ .../NoCustomIdempotencyDistinctor.java | 35 ++++ .../hook/IdempotencyCheckCommandHook.java | 60 +++++- .../IdempotencyCommandAutoConfiguration.java | 12 ++ .../web/IdempotencyResponseCaptureFilter.java | 5 +- .../idempotency/IdempotencyEndToEndTest.java | 31 +-- ...tencyEntityAndActionScopeEndToEndTest.java | 137 +++++++++++++ .../IdempotencyNoDistinctorEndToEndTest.java | 110 ++++++++++ .../IdempotencyCommandPropertyCheckTest.java | 39 +++- .../CustomIdempotencyDistinctorTest.java | 97 +++++++++ .../hook/IdempotencyCheckCommandHookTest.java | 85 +++++++- .../IdempotencyResponseCaptureFilterTest.java | 22 +- .../command/jdbc/store/JdbcCommandStore.java | 42 ++-- .../jdbc/store/domain/CommandEntity.java | 3 + .../store/domain/JdbcCommandRepository.java | 20 +- .../jdbc/store/mapping/JdbcCommandMapper.java | 2 + .../command/module-changelog-master.xml | 1 + .../parts/0006_idempotency_key_distinctor.xml | 70 +++++++ .../CommandIdempotencyKeyMigrationTest.java | 39 +++- .../IdempotencyKeyLookupCoverageTest.java | 85 ++++++++ .../jdbc/JdbcCommandStoreRetryTest.java | 6 +- .../command/jdbc/JdbcCommandStoreTest.java | 138 ++++++++++--- .../command-migration-test-changelog.xml | 1 + .../apache/fineract/command/core/Command.java | 15 ++ .../fineract/command/core/CommandStore.java | 20 +- .../chapters/architecture/command-audit.adoc | 8 + .../en/chapters/architecture/idempotency.adoc | 51 ++++- .../data/ClientCollateralCreateResponse.java | 4 + .../data/ClientCollateralDeleteResponse.java | 4 + .../data/ClientCollateralUpdateResponse.java | 6 + .../data/CollateralProductCreateResponse.java | 4 + .../data/CollateralProductDeleteResponse.java | 4 + .../data/CollateralProductUpdateResponse.java | 6 + .../data/LoanCollateralDeleteResponse.java | 4 + .../src/main/resources/application.properties | 4 + .../CommandHandlerResultRehydrationTest.java | 194 ++++++++++++++++++ 41 files changed, 1407 insertions(+), 126 deletions(-) create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorType.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/EntityAndActionNameCustomIdempotencyDistinctor.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml create mode 100644 fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java create mode 100644 fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java index a0280b47f5d..f1d1efa0186 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java @@ -36,6 +36,10 @@ private IdempotencyCommandConstants() {} public static final String COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE = COMMAND_IDEMPOTENCY_BASE_PACKAGE + ".check"; /** Marks the request that claimed a key, so the capture filter knows whose answer it is looking at. */ public static final String COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE = "fineract.command.idempotency.claimedKey"; + /** The distinctor the claimed key is unique together with; the capture filter needs both to find the row. */ + public static final String COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE = "fineract.command.idempotency.claimedDistinctor"; + public static final String COMMAND_IDEMPOTENCY_PROPERTY_CUSTOM_DISTINCTOR = COMMAND_IDEMPOTENCY_PROPERTIES_PREFIX + + ".custom-distinctor"; public static final int COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE = 20; public static final int COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE = 21; } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java index 191cc4b8cf6..6fec0c654dc 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java @@ -28,6 +28,7 @@ import lombok.Data; import lombok.NoArgsConstructor; import lombok.experimental.FieldNameConstants; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctorType; import org.springframework.boot.context.properties.ConfigurationProperties; @Builder @@ -71,4 +72,12 @@ public final class IdempotencyCommandProperties implements Serializable { */ @Builder.Default private Duration claimTimeout = Duration.ofMinutes(10); + + /** + * What an idempotency key is unique together with. {@code ENTITY_NAME_AND_ACTION_NAME}, the default, scopes it to + * the command's entity and action, the way the legacy command processing does; {@code NONE} makes a key unique per + * tenant across all commands. See {@link CustomIdempotencyDistinctorType}. + */ + @Builder.Default + private CustomIdempotencyDistinctorType customDistinctor = CustomIdempotencyDistinctorType.ENTITY_NAME_AND_ACTION_NAME; } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java index 6369ec6f2ee..067fafdc09d 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java @@ -19,6 +19,8 @@ package org.apache.fineract.command.idempotency.check; import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; import jakarta.annotation.PostConstruct; @@ -37,6 +39,13 @@ * idempotency without them and the first request for a key succeeds, the row stays {@code UNDER_PROCESSING} for ever, * and every repeat of that key is answered {@code 425 Too Early} - the key is poisoned, silently, and only from the * second request onwards. That is worth failing a startup over rather than warning about. + * + *

+ * Switching auditing on as a whole is not enough: the after hook records a command that completed and the error hook + * one that failed, and each can be switched off on its own. Without the after hook every successful command stays + * claimed; without the error hook every failed one does. Either way a repeat is told to retry until the claim times + * out, and is then told the command never finished - which, for a command that completed, is untrue. The before hook is + * not required: claiming the key has already written the row it would write. */ @Slf4j @RequiredArgsConstructor @@ -63,6 +72,18 @@ void check() { + "ever. Enable auditing, or set " + COMMAND_IDEMPOTENCY_PROPERTY_ENABLED + "=false."); } + requireHook(COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, audit.getHookPostEnabled(), "completed"); + requireHook(COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, audit.getHookErrorEnabled(), "failed"); + log.info("Command idempotency is enabled."); } + + private static void requireHook(String property, Boolean enabled, String outcome) { + if (!Boolean.TRUE.equals(enabled)) { + throw new IllegalStateException("Command idempotency is enabled but " + property + " is not: it is the audit hook that " + + "records a command that " + outcome + ", so without it such a command stays under processing and every " + + "repeat of its idempotency key is refused instead of being answered. Enable the hook, or set " + + COMMAND_IDEMPOTENCY_PROPERTY_ENABLED + "=false."); + } + } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java new file mode 100644 index 00000000000..b378064a528 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java @@ -0,0 +1,52 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import org.apache.fineract.command.core.Command; + +/** + * Decides what an idempotency key is unique together with. + * + *

+ * A command row is unique on its idempotency key and the value returned here, stored alongside the key as + * {@code custom_idempotency_distinctor}. Returning the same value for every command makes a key unique per tenant + * across all commands; returning something derived from the command scopes it, so that the same key may be used once + * per distinct value. A repeat is matched, and replayed, only against the row with the same key and the same value. + * + *

+ * The value is computed once, when the key is claimed, from the command as it is about to execute. It must be stable + * for a given request - a repeat of that request must produce the same value, or it is not recognised as a repeat - and + * it must not be {@code null} or longer than {@link #MAX_LENGTH} characters, the size of the column it is stored in. + * + *

+ * The implementation is chosen with {@code fineract.command.idempotency.custom-distinctor}; see + * {@link CustomIdempotencyDistinctorType}. An application can replace it altogether by defining its own bean of this + * type. + */ +@FunctionalInterface +public interface CustomIdempotencyDistinctor { + + /** The width of the {@code custom_idempotency_distinctor} column. */ + int MAX_LENGTH = 255; + + /** + * @return the value the command's idempotency key is unique together with; never {@code null} + */ + String distinctorFor(Command command); +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorType.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorType.java new file mode 100644 index 00000000000..eb0d850d783 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorType.java @@ -0,0 +1,44 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import java.util.function.Supplier; + +/** + * The values of {@code fineract.command.idempotency.custom-distinctor}, each naming the + * {@link CustomIdempotencyDistinctor} it selects. + */ +public enum CustomIdempotencyDistinctorType { + + /** {@link NoCustomIdempotencyDistinctor}: a key is unique per tenant across all commands. */ + NONE(NoCustomIdempotencyDistinctor::new), + + /** {@link EntityAndActionNameCustomIdempotencyDistinctor}: a key is unique per entity and action. */ + ENTITY_NAME_AND_ACTION_NAME(EntityAndActionNameCustomIdempotencyDistinctor::new); + + private final Supplier factory; + + CustomIdempotencyDistinctorType(Supplier factory) { + this.factory = factory; + } + + public CustomIdempotencyDistinctor create() { + return factory.get(); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/EntityAndActionNameCustomIdempotencyDistinctor.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/EntityAndActionNameCustomIdempotencyDistinctor.java new file mode 100644 index 00000000000..294a64f9fca --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/EntityAndActionNameCustomIdempotencyDistinctor.java @@ -0,0 +1,39 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import org.apache.fineract.command.core.Command; + +/** + * Scopes an idempotency key to what the command does and to what: the command's entity name and action name, as + * {@code m_permission} spells them, joined with {@value #SEPARATOR} - {@code LOAN|CREATE}, {@code PAYMENTTYPE|UPDATE}. + * + *

+ * This is how the legacy command processing scopes a key, so the same key may be used once per entity and action: a key + * reused on a different endpoint is executed as a new command rather than refused. + */ +public final class EntityAndActionNameCustomIdempotencyDistinctor implements CustomIdempotencyDistinctor { + + public static final String SEPARATOR = "|"; + + @Override + public String distinctorFor(Command command) { + return command.entityName() + SEPARATOR + command.actionName(); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java new file mode 100644 index 00000000000..6720f1fcbd3 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import org.apache.fineract.command.core.Command; + +/** + * Distinguishes nothing: every command gets the empty string, so an idempotency key is unique per tenant across all + * commands, and a key reused on a different endpoint is refused rather than executed. + */ +public final class NoCustomIdempotencyDistinctor implements CustomIdempotencyDistinctor { + + public static final String NONE = ""; + + @Override + public String distinctorFor(Command command) { + return NONE; + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java index 8ab57b85bb5..418726133c1 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -22,6 +22,7 @@ import static org.apache.fineract.command.core.CommandState.PROCESSED; import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; @@ -31,6 +32,7 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.Command; import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandReplay; @@ -40,6 +42,7 @@ import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; import org.apache.fineract.command.util.ServletHeaderUtil; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -58,6 +61,8 @@ final class IdempotencyCheckCommandHook implements CommandHookBefore ctx) { var command = ctx.getCommand(); @@ -67,10 +72,16 @@ public void onBefore(CommandContext ctx) { return; } + // the key is unique together with its distinctor, so the distinctor has to be on the command before it is + // claimed + var distinctorValue = distinctorFor(command); + + command.setCustomIdempotencyDistinctor(distinctorValue); + // claiming the key is what detects duplicates: the unique constraint means exactly one concurrent request can // win, whereas a read-only check followed by execution lets every racer through if (store.claim(command)) { - rememberClaimForResponseCapture(key); + rememberClaimForResponseCapture(key, distinctorValue); return; } @@ -79,10 +90,10 @@ public void onBefore(CommandContext ctx) { ctx.setSkipExecution(true); ctx.setSkipHooks(true); - var replay = replayFor(key); + var replay = replayFor(key, distinctorValue); - log.warn("Duplicate idempotency key detected: {} (state = {}, user = {}, ip = {})", key, replay.state(), - command.getInitiatedByUsername(), command.getIpAddress()); + log.warn("Duplicate idempotency key detected: {} (distinctor = '{}', state = {}, user = {}, ip = {})", key, distinctorValue, + replay.state(), command.getInitiatedByUsername(), command.getIpAddress()); if (UNDER_PROCESSING.equals(replay.state())) { if (abandoned(replay)) { @@ -93,7 +104,7 @@ public void onBefore(CommandContext ctx) { throw new CommandIdempotencyInProgressException(key, replay.response()); } - if (!store.matchesStoredRequest(key, command.getPayload())) { + if (!store.matchesStoredRequest(key, distinctorValue, command.getPayload())) { // replaying here would answer a question that was never asked throw new CommandIdempotencyConflictException(key, null); } @@ -120,17 +131,23 @@ public void onBefore(CommandContext ctx) { * deserialises - leaves the original answer unreachable. Letting that surface as a server error would say the * request failed, and answering with an empty body would say it succeeded with no content; both are untrue. The key * has been used and its answer cannot be produced, so the request is refused and told why. + * + *

+ * Only a command that completed stores a result of its own, so a result that will not rehydrate means the command + * was carried out. The answer says so, and must not suggest sending it again under a new key: that would carry it + * out a second time, which is the duplicate this mechanism exists to prevent. */ - private CommandReplay replayFor(String key) { + private CommandReplay replayFor(String key, String distinctorValue) { try { - return store.getReplayByKey(key); + return store.getReplayByKey(key, distinctorValue); } catch (RuntimeException e) { log.error("Cannot reconstruct the stored result for idempotency key {}", key, e); throw new CommandIdempotencyConflictException(key, Map.of("idempotencyKey", key, "error", - "The result stored under this idempotency key cannot be reconstructed, so the original answer " - + "cannot be replayed. Retry with a new idempotency key."), + "The command sent with this idempotency key was carried out, but the result stored for it cannot " + + "be reconstructed, so the original answer cannot be replayed. Do not send it again " + + "under a new idempotency key: that would carry it out a second time."), e); } } @@ -205,11 +222,34 @@ private static void markServedFromCache(String key) { } } - private static void rememberClaimForResponseCapture(String key) { + private static void rememberClaimForResponseCapture(String key, String distinctorValue) { var attributes = RequestContextHolder.getRequestAttributes(); if (attributes != null) { attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, key, RequestAttributes.SCOPE_REQUEST); + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE, distinctorValue, RequestAttributes.SCOPE_REQUEST); + } + } + + /** + * The configured distinctor's value for this command, refused here rather than by the database when it cannot be + * stored: the column does not take {@code null}, and a value longer than the column would fail the claim with a + * data error instead of a message that names the distinctor. + */ + private String distinctorFor(Command command) { + var value = distinctor.distinctorFor(command); + + if (value == null) { + throw new IllegalStateException(distinctor.getClass().getName() + " returned no idempotency distinctor for " + + command.getClass().getName() + "; return the empty string to distinguish nothing."); } + + if (value.length() > CustomIdempotencyDistinctor.MAX_LENGTH) { + throw new IllegalStateException( + distinctor.getClass().getName() + " returned an idempotency distinctor of " + value.length() + " characters for " + + command.getClass().getName() + "; at most " + CustomIdempotencyDistinctor.MAX_LENGTH + " can be stored."); + } + + return value; } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java index 866fdd2b93d..f5ebec06614 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java @@ -25,8 +25,10 @@ import org.apache.fineract.command.core.CommandStore; import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; import org.apache.fineract.command.idempotency.web.IdempotencyResponseCaptureFilter; import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.boot.web.servlet.FilterRegistrationBean; @@ -56,4 +58,14 @@ FilterRegistrationBean idempotencyResponseCapt return registration; } + + /** + * What an idempotency key is unique together with, as {@code fineract.command.idempotency.custom-distinctor} + * selects. Backs off for a distinctor the application defines itself. + */ + @Bean + @ConditionalOnMissingBean + CustomIdempotencyDistinctor customIdempotencyDistinctor(IdempotencyCommandProperties properties) { + return properties.getCustomDistinctor().create(); + } } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java index 977fc51ce5d..685e7817e69 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilter.java @@ -18,6 +18,7 @@ */ package org.apache.fineract.command.idempotency.web; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; import jakarta.servlet.FilterChain; @@ -88,10 +89,12 @@ private void record(HttpServletRequest request, ContentCachingResponseWrapper wr return; } + // the key is unique together with its distinctor, so both are needed to find the row this request claimed + var distinctor = (String) request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE); var body = replayableBody(key, wrapper); try { - store.recordResponse(key, wrapper.getStatus(), body); + store.recordResponse(key, distinctor == null ? "" : distinctor, wrapper.getStatus(), body); } catch (RuntimeException e) { // the command itself has been processed and answered; failing here must not change that outcome. The // record is left claiming an outcome it cannot produce, so the failure is logged loudly - but with the diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java index 4e836622571..c5a683f80e5 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEndToEndTest.java @@ -61,6 +61,9 @@ @ContextConfiguration(classes = TestConfiguration.class) public class IdempotencyEndToEndTest extends CommandBaseTest { + /** The distinctor of the {@code /sync} command under the default, {@code ENTITY_NAME_AND_ACTION_NAME}. */ + private static final String SYNC = "DUMMY|CREATE"; + @LocalServerPort private int port; @@ -141,22 +144,6 @@ public void aKeyReusedForADifferentRequestIsRejected() { assertEquals(409, different.getStatusCode().value(), "Reusing a key for a different request must not replay the first answer."); } - @Test - public void aKeyIsUniqueAcrossCommandsNotOnlyWithinOne() { - var key = UUID.randomUUID().toString(); - - var first = post("/sync", "hello", key); - - assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); - - // deliberately stricter than the old command processing, which scopes a key by action and entity name and so - // would execute this. A key here identifies one command for the whole tenant. - var otherCommand = post("/error", "boom", key); - - assertEquals(409, otherCommand.getStatusCode().value(), - "Reusing a key for a different command must be rejected, not executed and not replayed."); - } - @Test public void concurrentRepeatsExecuteTheCommandOnlyOnce() throws Exception { var threads = 6; @@ -201,6 +188,8 @@ public void aRequestForACommandStillRunningIsToldItIsTooEarly() { inFlight.setPayload(DummyRequest.builder().content("hello").build()); inFlight.setIdempotencyKey(key); + // as the hook would have claimed it under the default distinctor + inFlight.setCustomIdempotencyDistinctor(SYNC); inFlight.setCreatedAt(java.time.Instant.now()); // claim the key without ever completing it, which is what another node mid-request looks like @@ -218,7 +207,7 @@ public void oneCommandIsRecordedAndRepeatsNeverAddAnother() { post("/sync", "hello", key); - var recorded = repository.findOneByIdempotencyKey(key).orElseThrow(); + var recorded = repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, SYNC).orElseThrow(); assertEquals(CommandState.PROCESSED, recorded.getState(), "A processed command must be audited as processed."); assertNotNull(recorded.getResponse(), "The result the command produced must be recorded."); @@ -228,10 +217,12 @@ public void oneCommandIsRecordedAndRepeatsNeverAddAnother() { post("/sync", "hello", key); post("/sync", "hello", key); - assertEquals(1, repository.findAll().stream().filter(e -> key.equals(e.getIdempotencyKey())).count(), - "Repeats must not add command records."); + assertEquals(1, + repository.findAll().stream() + .filter(e -> key.equals(e.getIdempotencyKey()) && SYNC.equals(e.getCustomIdempotencyDistinctor())).count(), + "Repeats must not add command records under the key and its distinctor."); - var afterRepeats = repository.findOneByIdempotencyKey(key).orElseThrow(); + var afterRepeats = repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, SYNC).orElseThrow(); assertEquals(CommandState.PROCESSED, afterRepeats.getState(), "A repeat must not change the recorded outcome."); } diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java new file mode 100644 index 00000000000..3b40e0fccc8 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java @@ -0,0 +1,137 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, under the default distinctor, {@code ENTITY_NAME_AND_ACTION_NAME}: + * the key is scoped to the command's entity and action, the way the legacy command processing scopes it. Nothing is + * configured here on purpose, so that this also pins which distinctor is the default. The sample commands are + * {@code DUMMY|CREATE} on {@code /sync} and {@code DUMMY|ERROR} on {@code /error}. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +public class IdempotencyEntityAndActionScopeEndToEndTest extends CommandBaseTest { + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void theSameKeyOnAnotherCommandIsExecutedAsANewCommand() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + var otherCommand = post("/error", "boom", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + assertTrue(otherCommand.getStatusCode().is4xxClientError(), + "Another entity and action under the same key is a new command, so it must run - and this one fails - " + + "rather than be refused as a conflict; got " + otherCommand.getStatusCode()); + assertFalse(servedFromCache(otherCommand), "It was executed, not replayed."); + + assertEquals(CommandState.PROCESSED, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "DUMMY|CREATE").orElseThrow().getState()); + assertEquals(CommandState.ERROR, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "DUMMY|ERROR").orElseThrow().getState()); + } + + @Test + public void aRepeatUnderTheSameEntityAndActionIsReplayed() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + post("/error", "boom", key); + + var repeat = post("/sync", "hello", key); + + assertTrue(servedFromCache(repeat), "A repeat under the same entity and action must be replayed."); + assertEquals(first.getStatusCode(), repeat.getStatusCode()); + assertEquals(first.getBody(), repeat.getBody(), "It must be answered from its own row, not the other command's."); + } + + @Test + public void aRepeatOfTheFailedCommandIsAnsweredWithItsOwnFailure() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + var failure = post("/error", "boom", key); + var repeat = post("/error", "boom", key); + + assertTrue(servedFromCache(repeat), "A repeat of the failed command must be replayed."); + assertEquals(failure.getStatusCode(), repeat.getStatusCode(), + "The status recorded for the failed command must be found under its own distinctor."); + assertEquals(failure.getBody(), repeat.getBody()); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content(content).build(), headers), String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst(IDEMPOTENT_CACHE_HEADER)); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java new file mode 100644 index 00000000000..55c5e2b99f6 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java @@ -0,0 +1,110 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.test.context.TestPropertySource; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, with {@code NONE}: nothing distinguishes a key, so it identifies + * one command for the whole tenant - stricter than the legacy command processing, which scopes a key by entity and + * action. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +@TestPropertySource(properties = "fineract.command.idempotency.custom-distinctor=NONE") +public class IdempotencyNoDistinctorEndToEndTest extends CommandBaseTest { + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void aKeyIsUniqueAcrossCommandsNotOnlyWithinOne() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + + var otherCommand = post("/error", "boom", key); + + assertEquals(409, otherCommand.getStatusCode().value(), + "Reusing a key for a different command must be rejected, not executed and not replayed."); + } + + @Test + public void theKeyIsStoredWithTheEmptyDistinctor() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + assertEquals(CommandState.PROCESSED, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "").orElseThrow().getState(), + "Under NONE the key is claimed with the empty distinctor."); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content(content).build(), headers), String.class); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java index b4cfa6882eb..c45c444a579 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java @@ -26,12 +26,13 @@ import org.springframework.boot.test.context.runner.ApplicationContextRunner; /** - * Covers the four ways idempotency and auditing can be configured against each other. + * Covers the ways idempotency and auditing can be configured against each other. * *

- * Only one of them is a mistake, and it is the one that would otherwise go unnoticed: idempotency on, auditing off. - * Nothing fails at startup, the first request for a key is answered normally, and the breakage shows up only when a - * client retries - as a 425 that never resolves. The point of the check is to turn that into a startup failure. + * The mistakes are the ones that would otherwise go unnoticed: idempotency on with auditing off, or with the audit hook + * that records a completed or a failed command off. Nothing fails at startup, the first request for a key is answered + * normally, and the breakage shows up only when a client retries - as a 425 that does not resolve. The point of the + * check is to turn that into a startup failure. */ class IdempotencyCommandPropertyCheckTest { @@ -57,6 +58,36 @@ void idempotencyWithoutAuditingRefusesToStart() { .rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("fineract.command.audit.enabled")); } + @Test + void idempotencyWithoutTheAfterHookRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.hook-post-enabled=false").run(context -> assertThat(context) + .as("Nothing would record a completed command, so its repeats would be told it never finished.").hasFailed().getFailure() + .rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("fineract.command.audit.hook-post-enabled")); + } + + @Test + void idempotencyWithoutTheErrorHookRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.hook-error-enabled=false") + .run(context -> assertThat(context) + .as("Nothing would record a failed command, so its repeats would never be answered with the failure.").hasFailed() + .getFailure().rootCause().isInstanceOf(IllegalStateException.class) + .hasMessageContaining("fineract.command.audit.hook-error-enabled")); + } + + @Test + void idempotencyWithoutTheBeforeHookStarts() { + contextRunner.withPropertyValues("fineract.command.audit.hook-pre-enabled=false").run( + context -> assertThat(context).as("Claiming the key already writes the row the before hook would write.").hasNotFailed()); + } + + @Test + void auditHooksOffWithoutIdempotencyStarts() { + contextRunner + .withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.hook-post-enabled=false", + "fineract.command.audit.hook-error-enabled=false") + .run(context -> assertThat(context).as("Without idempotency nothing depends on the hooks.").hasNotFailed()); + } + @Test void bothOffStarts() { contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.enabled=false").run( diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java new file mode 100644 index 00000000000..2f6c9021bb0 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java @@ -0,0 +1,97 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; + +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.idempotency.starter.IdempotencyCommandAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * Pins what each distinctor returns and which one {@code fineract.command.idempotency.custom-distinctor} selects. + */ +class CustomIdempotencyDistinctorTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(IdempotencyCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)); + + @Test + void noneDistinguishesNothing() { + assertThat(new NoCustomIdempotencyDistinctor().distinctorFor(command("LOAN", "CREATE"))).isEmpty(); + } + + @Test + void entityAndActionNameJoinsTheEntityAndTheActionWithABar() { + assertThat(new EntityAndActionNameCustomIdempotencyDistinctor().distinctorFor(command("LOAN", "CREATE"))).isEqualTo("LOAN|CREATE"); + } + + @Test + void entityNameAndActionNameIsSelectedWhenNothingIsConfigured() { + contextRunner.run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class) + .isInstanceOf(EntityAndActionNameCustomIdempotencyDistinctor.class)); + } + + @Test + void noneSelectsNone() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=NONE").run(context -> assertThat(context) + .getBean(CustomIdempotencyDistinctor.class).isInstanceOf(NoCustomIdempotencyDistinctor.class)); + } + + @Test + void entityNameAndActionNameSelectsEntityAndActionName() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=ENTITY_NAME_AND_ACTION_NAME") + .run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class) + .isInstanceOf(EntityAndActionNameCustomIdempotencyDistinctor.class)); + } + + @Test + void anUnknownValueRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=ENTITY_ONLY") + .run(context -> assertThat(context).as("A typo must not silently fall back to another scope.").hasFailed()); + } + + @Test + void aDistinctorTheApplicationDefinesReplacesTheConfiguredOne() { + CustomIdempotencyDistinctor own = command -> "own"; + + contextRunner.withBean(CustomIdempotencyDistinctor.class, () -> own) + .run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class).isSameAs(own)); + } + + private static Command command(String entity, String action) { + return new Command<>() { + + @Override + public String entityName() { + return entity; + } + + @Override + public String actionName() { + return action; + } + }; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java index 8b52b430c99..b3f15f0e7e8 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -46,6 +46,9 @@ import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; +import org.apache.fineract.command.idempotency.distinctor.EntityAndActionNameCustomIdempotencyDistinctor; +import org.apache.fineract.command.idempotency.distinctor.NoCustomIdempotencyDistinctor; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; @@ -64,7 +67,7 @@ class IdempotencyCheckCommandHookTest { @BeforeEach void setUp() { - hook = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build()); + hook = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build(), new NoCustomIdempotencyDistinctor()); } @Test @@ -86,7 +89,7 @@ void winningTheClaimLetsTheCommandExecute() { hook.onBefore(ctx); assertFalse(ctx.isSkipExecution(), "The request that claims the key must be executed."); - verify(store, never()).getReplayByKey(anyString()); + verify(store, never()).getReplayByKey(anyString(), anyString()); } @Test @@ -100,7 +103,7 @@ void anUnfinishedCommandAnswersTooEarly() { assertEquals(425, exception.getStatusCode(), "An unfinished command must answer 425 Too Early."); assertTrue(ctx.isSkipExecution(), "An in-flight command must not be executed a second time."); // the request is not compared here: there is nothing stored to compare a response against yet - verify(store, never()).matchesStoredRequest(anyString(), any()); + verify(store, never()).matchesStoredRequest(anyString(), anyString(), any()); } @Test @@ -110,7 +113,7 @@ void aProcessedCommandIsReplayedByHandingBackItsOwnResult() { var stored = Map.of("resourceId", 7); duplicate(new CommandReplay(PROCESSED, null, stored, Instant.now())); - when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); hook.onBefore(ctx); @@ -127,7 +130,7 @@ void aProcessedCommandWithOnlyACapturedAnswerIsThrownWithItsRecordedStatus() { // no result object to hand back, so the answer captured as it went out is replayed as the text it is, and // the status has to come from the record because nothing else can derive it duplicate(new CommandReplay(PROCESSED, 201, "{\"resourceId\":7}", Instant.now())); - when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); var exception = assertThrows(CommandIdempotencyProcessedException.class, () -> hook.onBefore(ctx)); @@ -142,7 +145,7 @@ void aFailedCommandIsReplayedAsTheSameFailure() { var stored = Map.of("error", "bad request"); duplicate(new CommandReplay(ERROR, 400, stored, Instant.now())); - when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); // this is what the old processing does: a repeat of a failure fails identically rather than being retried var exception = assertThrows(CommandIdempotencyFailedException.class, () -> hook.onBefore(ctx)); @@ -157,7 +160,7 @@ void aKeyReusedForADifferentRequestConflicts() { var ctx = context(KEY); duplicate(new CommandReplay(PROCESSED, 200, Map.of(), Instant.now())); - when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(false); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(false); var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); @@ -169,7 +172,7 @@ void anUnrecognisedStateConflictsRatherThanGuessing() { var ctx = context(KEY); duplicate(new CommandReplay(UNKNOWN, null, null, Instant.now())); - when(store.matchesStoredRequest(KEY, "request-payload")).thenReturn(true); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); } @@ -179,7 +182,7 @@ void aStoredResultThatCannotBeReconstructedIsRefusedRatherThanGuessedAt() { var ctx = context(KEY); when(store.claim(any())).thenReturn(false); - when(store.getReplayByKey(KEY)).thenThrow(new IllegalStateException("Cannot rehydrate a stored command result")); + when(store.getReplayByKey(KEY, "")).thenThrow(new IllegalStateException("Cannot rehydrate a stored command result")); var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); @@ -187,6 +190,10 @@ void aStoredResultThatCannotBeReconstructedIsRefusedRatherThanGuessedAt() { "The key has been used and its answer cannot be produced, which is neither a success nor a failure of this request."); assertTrue(String.valueOf(exception.getResponse()).contains("cannot be reconstructed"), "The answer must say what went wrong rather than coming back empty."); + assertTrue(String.valueOf(exception.getResponse()).contains("was carried out"), + "Only a completed command stores a result, so the answer must say the command took effect."); + assertTrue(String.valueOf(exception.getResponse()).contains("Do not send it again"), + "Inviting a retry under a new key would execute a command that already took effect a second time."); } @Test @@ -216,7 +223,65 @@ void aClaimThatIsStillWithinItsTimeIsToldToComeBack() { private void duplicate(CommandReplay replay) { when(store.claim(any())).thenReturn(false); - when(store.getReplayByKey(KEY)).thenReturn(replay); + when(store.getReplayByKey(KEY, "")).thenReturn(replay); + } + + @Test + void theDistinctorIsOnTheCommandBeforeItsKeyIsClaimed() { + var scoped = hookWith(new EntityAndActionNameCustomIdempotencyDistinctor()); + var ctx = context(KEY); + + when(store.claim(any())).thenAnswer(invocation -> { + assertEquals("DOCUMENT|CREATE", invocation.>getArgument(0).getCustomIdempotencyDistinctor(), + "The key is unique together with the distinctor, so the claim has to carry it."); + + return true; + }); + + scoped.onBefore(ctx); + + assertEquals("DOCUMENT|CREATE", ctx.getCommand().getCustomIdempotencyDistinctor()); + assertFalse(ctx.isSkipExecution(), "A command that claimed its key must be executed."); + } + + @Test + void aRepeatIsLookedUpUnderItsOwnDistinctor() { + var scoped = hookWith(new EntityAndActionNameCustomIdempotencyDistinctor()); + var ctx = context(KEY); + var replay = new CommandReplay(ERROR, 400, "{\"error\":\"bad request\"}", Instant.now()); + + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY, "DOCUMENT|CREATE")).thenReturn(replay); + when(store.matchesStoredRequest(KEY, "DOCUMENT|CREATE", "request-payload")).thenReturn(true); + + var exception = assertThrows(CommandIdempotencyFailedException.class, () -> scoped.onBefore(ctx)); + + assertEquals(400, exception.getStatusCode(), "The repeat must be answered from the row with the same key and distinctor."); + } + + @Test + void aDistinctorThatReturnsNothingIsRefusedBeforeTheKeyIsClaimed() { + var broken = hookWith(command -> null); + + var exception = assertThrows(IllegalStateException.class, () -> broken.onBefore(context(KEY))); + + assertTrue(exception.getMessage().contains("empty string"), "The message must say what to return instead."); + verifyNoInteractions(store); + } + + @Test + void aDistinctorTooLongForItsColumnIsRefusedBeforeTheKeyIsClaimed() { + var broken = hookWith(command -> "x".repeat(CustomIdempotencyDistinctor.MAX_LENGTH + 1)); + + var exception = assertThrows(IllegalStateException.class, () -> broken.onBefore(context(KEY))); + + assertTrue(exception.getMessage().contains(String.valueOf(CustomIdempotencyDistinctor.MAX_LENGTH)), + "The message must name the limit."); + verifyNoInteractions(store); + } + + private IdempotencyCheckCommandHook hookWith(CustomIdempotencyDistinctor distinctor) { + return new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build(), distinctor); } private static CommandContext context(String key) { diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java index 5668afa365e..f95295325b4 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java @@ -18,6 +18,7 @@ */ package org.apache.fineract.command.idempotency.web; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE; import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; @@ -83,7 +84,7 @@ void anAnswerThatIsNotJsonIsReportedWithoutItsBody() throws Exception { var csv = "id,amount\n7,1.50\n"; var response = runWith("text/csv", csv); - verify(store).recordResponse(eq(KEY), eq(200), isNull()); + verify(store).recordResponse(eq(KEY), eq(""), eq(200), isNull()); assertFalse(logged().contains("id,amount"), "The body must not reach the log: responses here carry customer data."); assertTrue( @@ -96,7 +97,7 @@ && logged().contains(csv.getBytes(java.nio.charset.StandardCharsets.UTF_8).lengt @Test void anAnswerThatCannotBeRecordedIsReportedWithoutItsBody() throws Exception { - doThrow(new IllegalStateException("the database is unavailable")).when(store).recordResponse(eq(KEY), eq(200), + doThrow(new IllegalStateException("the database is unavailable")).when(store).recordResponse(eq(KEY), eq(""), eq(200), eq("{\"amount\":1.50}")); runWith("application/json", "{\"amount\":1.50}"); @@ -111,17 +112,32 @@ void anAnswerThatCannotBeRecordedIsReportedWithoutItsBody() throws Exception { void aJsonAnswerIsRecordedRatherThanLogged() throws Exception { runWith("application/json", "{\"amount\":1.50}"); - verify(store).recordResponse(KEY, 200, "{\"amount\":1.50}"); + verify(store).recordResponse(KEY, "", 200, "{\"amount\":1.50}"); assertTrue(logged().isEmpty(), "Nothing is lost on the ordinary path, so nothing is logged about it."); } + @Test + void theAnswerIsRecordedAgainstTheDistinctorTheKeyWasClaimedWith() throws Exception { + runWith("application/json", "{\"amount\":1.50}", "PAYMENTTYPE|CREATE"); + + verify(store).recordResponse(KEY, "PAYMENTTYPE|CREATE", 200, "{\"amount\":1.50}"); + } + private MockHttpServletResponse runWith(String contentType, String body) throws Exception { + return runWith(contentType, body, null); + } + + private MockHttpServletResponse runWith(String contentType, String body, String distinctor) throws Exception { var request = new MockHttpServletRequest("POST", "/commands"); request.addHeader(IdempotencyCommandProperties.builder().build().getKeyHeaderName(), KEY); request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, KEY); + if (distinctor != null) { + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE, distinctor); + } + var response = new MockHttpServletResponse(); var chain = new MockFilterChain() { diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java index b96a79590eb..d320201f596 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java @@ -27,6 +27,7 @@ import io.github.resilience4j.retry.annotation.Retry; import java.io.IOException; import java.nio.file.Path; +import java.time.Instant; import java.util.Optional; import java.util.UUID; import lombok.RequiredArgsConstructor; @@ -67,20 +68,20 @@ public Command getById(Long id) { } @Override - public Command getByKey(String key) { - return repository.findOneByIdempotencyKey(key).map(mapper::map).orElse(null); + public Command getByKey(String key, String distinctor) { + return repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor).map(mapper::map).orElse(null); } @Override - public boolean existsByKey(String key) { - return repository.existsByIdempotencyKey(key); + public boolean existsByKey(String key, String distinctor) { + return repository.existsByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor); } @Override - public CommandReplay getReplayByKey(String key) { - return repository.findOneByIdempotencyKey(key) + public CommandReplay getReplayByKey(String key, String distinctor) { + return repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor) .map(entity -> new CommandReplay(entity.getState(), entity.getResponseStatusCode(), - replayResponse(key, entity.getResponse()), entity.getCreatedAt())) + replayResponse(key, distinctor, entity.getResponse()), entity.getCreatedAt())) .orElseGet(() -> new CommandReplay(UNKNOWN, null, null, null)); } @@ -93,7 +94,7 @@ public CommandReplay getReplayByKey(String key) { * A command that produced no result of its own leaves only what was captured as it went out, and that is replayed * as the text it was stored as. Re-rendering it would change the bytes: a decimal written as 1.50 comes back 1.5. */ - private Object replayResponse(String key, JsonNode stored) { + private Object replayResponse(String key, String distinctor, JsonNode stored) { if (isNull(stored)) { return null; } @@ -102,20 +103,27 @@ private Object replayResponse(String key, JsonNode stored) { return jsonMapper.map(stored); } - return repository.findResponseTextByIdempotencyKey(key).orElse(null); + return repository.findResponseTextByIdempotencyKey(key, distinctor).orElse(null); } @Override @Retry(name = "commandStore") - public void recordResponse(String key, int statusCode, String body) { - var updated = repository.updateResponse(key, statusCode, body); + public void recordResponse(String key, String distinctor, int statusCode, String body) { + var updated = repository.updateResponse(key, distinctor, statusCode, body); - log.debug("Recorded response {} for idempotency key {} ({} row(s))", statusCode, key, updated); + log.debug("Recorded response {} for idempotency key {} (distinctor '{}', {} row(s))", statusCode, key, distinctor, updated); } @Override @Retry(name = "commandStore") public boolean claim(Command command) { + // the claim's age is what tells an abandoned claim from a running one, so it must never be stored without one. + // The timestamp hook normally sets it as the request arrives, but it can be switched off; set on the command + // rather than only on the row, so that the audit hooks rewriting the row later keep the same value + if (isNull(command.getCreatedAt())) { + command.setCreatedAt(Instant.now()); + } + final var commandEntity = mapper.map(command); commandEntity.setState(UNDER_PROCESSING); @@ -124,12 +132,14 @@ public boolean claim(Command command) { repository.save(commandEntity); command.setCommandId(commandEntity.getId()); - log.debug("Claimed idempotency key {} with command id {}", command.getIdempotencyKey(), commandEntity.getId()); + log.debug("Claimed idempotency key {} (distinctor '{}') with command id {}", command.getIdempotencyKey(), + command.getCustomIdempotencyDistinctor(), commandEntity.getId()); return true; } catch (RuntimeException e) { if (isDuplicateKey(e)) { - log.debug("Idempotency key {} is already claimed", command.getIdempotencyKey()); + log.debug("Idempotency key {} (distinctor '{}') is already claimed", command.getIdempotencyKey(), + command.getCustomIdempotencyDistinctor()); return false; } @@ -139,7 +149,7 @@ public boolean claim(Command command) { } @Override - public boolean matchesStoredRequest(String key, Object payload) { + public boolean matchesStoredRequest(String key, String distinctor, Object payload) { if (isNull(payload)) { return false; } @@ -147,7 +157,7 @@ public boolean matchesStoredRequest(String key, Object payload) { // compared as text rather than as parsed nodes: the stored text was written by this same mapper, so an // identical request produces identical text, while parsing would round a decimal through a double and make // two amounts that differ only in their last digits look like the same request - return repository.findRequestTextByIdempotencyKey(key) + return repository.findRequestTextByIdempotencyKey(key, distinctor) .map(stored -> stored.equals(objectMapper.writeValueAsString(jsonMapper.map(payload)))).orElse(false); } diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java index 2e4573d19b0..afa37fa1290 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java @@ -72,6 +72,9 @@ public class CommandEntity implements Serializable { @Column("rejected_by_username") private String rejectedByUsername; + @Column("custom_idempotency_distinctor") + private String customIdempotencyDistinctor; + @Column("entity_name") private String entityName; diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java index 365c5b8cde7..9f6d672daf7 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java @@ -27,9 +27,10 @@ public interface JdbcCommandRepository extends ListCrudRepository, QueryByExampleExecutor { - Optional findOneByIdempotencyKey(String idempotencyKey); + Optional findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(String idempotencyKey, + String customIdempotencyDistinctor); - boolean existsByIdempotencyKey(String idempotencyKey); + boolean existsByIdempotencyKeyAndCustomIdempotencyDistinctor(String idempotencyKey, String customIdempotencyDistinctor); /** * Records what the original request was answered with, but only for a command that stored no result of its own. @@ -46,23 +47,26 @@ public interface JdbcCommandRepository extends ListCrudRepository findResponseTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey); + @Query("SELECT response FROM m_command WHERE idempotency_key = :idempotencyKey AND custom_idempotency_distinctor = :distinctor") + Optional findResponseTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey, + @Param("distinctor") String distinctor); /** * Reads the stored request as the exact text it was stored as, for comparing a retry against it. Comparing parsed * nodes instead would collapse a decimal to a double, so two amounts differing beyond a double's precision would * compare equal and the wrong answer would be replayed. */ - @Query("SELECT request FROM m_command WHERE idempotency_key = :idempotencyKey") - Optional findRequestTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey); + @Query("SELECT request FROM m_command WHERE idempotency_key = :idempotencyKey AND custom_idempotency_distinctor = :distinctor") + Optional findRequestTextByIdempotencyKey(@Param("idempotencyKey") String idempotencyKey, + @Param("distinctor") String distinctor); } diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java index 1a47c3eb6db..86f52168d6b 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java @@ -43,6 +43,7 @@ public interface JdbcCommandMapper { @Mapping(source = "payload", target = "request") @Mapping(source = "ipAddress", target = "ipAddress") @Mapping(source = "idempotencyKey", target = "idempotencyKey") + @Mapping(source = "customIdempotencyDistinctor", target = "customIdempotencyDistinctor") @Mapping(source = "error", target = "error") @Mapping(expression = "java(source.entityName())", target = "entityName") @Mapping(expression = "java(source.actionName())", target = "actionName") @@ -65,6 +66,7 @@ public interface JdbcCommandMapper { @Mapping(expression = "java(source.entityName())", target = "entityName") @Mapping(expression = "java(source.actionName())", target = "actionName") @Mapping(source = "source.idempotencyKey", target = "idempotencyKey") + @Mapping(source = "source.customIdempotencyDistinctor", target = "customIdempotencyDistinctor") @Mapping(source = "source.error", target = "error") @Mapping(source = "response", target = "response") @Mapping(ignore = true, target = "state") diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml index 6992d1ee3d8..0b55e10eab8 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml @@ -27,5 +27,6 @@ + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml new file mode 100644 index 00000000000..3f63e70e409 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml @@ -0,0 +1,70 @@ + + + + + + + What an idempotency key is unique together with, as the configured CustomIdempotencyDistinctor computes it + when the key is claimed. The empty string means nothing distinguishes the key, which is what every existing + row gets and what a command without a key is stored with: not null, so that the composite unique constraint + below compares two empty values as equal rather than treating two nulls as distinct. + + + + + + + + + + Make the idempotency key unique together with its distinctor. Added before the key-only constraint is + dropped, so there is no moment at which the key is not unique. Every existing row has the empty distinctor + and the key-only constraint already holds, so no existing row can violate this one. + + + + + + Drop the key-only unique constraint, which would otherwise still refuse the same key under a different + distinctor. + + + + + + + + diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java index 9e0ffd8dc12..7d9aec2791a 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java @@ -119,6 +119,20 @@ private void verify(JdbcDatabaseContainer container, String context) throws E assertEquals(3, count(connection, "idempotency_key IS NULL"), "The unique constraint must not apply to null keys."); assertThrows(SQLException.class, () -> insert(connection, 103, "KEEP-1-duplicate-2"), "A suffixed key must be unique as well."); + + // every row that predates the distinctor gets the empty one, and so does a row inserted without one + assertEquals(count(connection, "1 = 1"), count(connection, "custom_idempotency_distinctor = ''"), + "Existing rows and rows inserted without a distinctor must get the empty one, never null."); + + // the key is unique together with its distinctor, not on its own + insert(connection, 104, "KEEP-1", "LOAN|CREATE"); + assertEquals(2, count(connection, "idempotency_key = 'KEEP-1'"), "The same key under another distinctor must be accepted."); + assertThrows(SQLException.class, () -> insert(connection, 105, "KEEP-1", "LOAN|CREATE"), + "The same key under the same distinctor must still be rejected."); + + // the key-only constraint cannot be restored over a key stored under two distinctors, which is the + // rollback's documented limit; the test removes the row so that it can roll back past it + delete(connection, 104); } rollbackUniqueConstraint(container, context); @@ -141,13 +155,13 @@ private void migrate(JdbcDatabaseContainer container, String context) throws } /** - * Reverts the unique constraint, which means also reverting the response-cache and action/entity changesets stacked - * on top of it. Both databases apply the same number of changesets from that point on, so this count has to grow - * with every part added after 0003. + * Reverts the unique constraint, which means also reverting the response-cache, action/entity and distinctor + * changesets stacked on top of it. Both databases apply the same number of changesets from that point on, so this + * count has to grow with every changeset added after 0003. */ private void rollbackUniqueConstraint(JdbcDatabaseContainer container, String context) throws Exception { try (var connection = connect(container); var liquibase = liquibase(connection)) { - liquibase.rollback(3, new Contexts(context), new LabelExpression()); + liquibase.rollback(6, new Contexts(context), new LabelExpression()); } } @@ -165,6 +179,23 @@ private static int count(Connection connection, String where) throws SQLExceptio } } + private static void insert(Connection connection, long id, String key, String distinctor) throws SQLException { + try (var statement = connection.prepareStatement( + "INSERT INTO m_command (id, idempotency_key, custom_idempotency_distinctor, state) VALUES (?, ?, ?, 'PROCESSED')")) { + statement.setLong(1, id); + statement.setString(2, key); + statement.setString(3, distinctor); + statement.executeUpdate(); + } + } + + private static void delete(Connection connection, long id) throws SQLException { + try (var statement = connection.prepareStatement("DELETE FROM m_command WHERE id = ?")) { + statement.setLong(1, id); + statement.executeUpdate(); + } + } + private static void insert(Connection connection, long id, String key) throws SQLException { try (var statement = connection.prepareStatement("INSERT INTO m_command (id, idempotency_key, state) VALUES (?, ?, 'PROCESSED')")) { statement.setLong(1, id); diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java new file mode 100644 index 00000000000..c74480f633e --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java @@ -0,0 +1,85 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.lang.reflect.Method; +import java.lang.reflect.Parameter; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Locale; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.junit.jupiter.api.Test; +import org.springframework.data.jdbc.repository.query.Query; + +/** + * Holds every lookup of a command by its idempotency key to also matching its distinctor. + * + *

+ * The key is unique only together with {@code custom_idempotency_distinctor}, so the same key can be on several rows. A + * lookup by the key alone finds whichever of them comes first - a repeat answered with another command's result, or a + * response recorded against another command's row - and a derived single-row finder fails outright. Nothing else + * notices while every row under a key has the same distinctor, which is why this is checked by name and query text + * rather than left to a test that happens to use two distinctors. + */ +class IdempotencyKeyLookupCoverageTest { + + @Test + void everyRepositoryQueryByKeyAlsoMatchesTheDistinctor() { + var keyOnly = new ArrayList(); + + for (Method method : JdbcCommandRepository.class.getDeclaredMethods()) { + var query = method.getAnnotation(Query.class); + + if (query != null) { + var sql = query.value().toLowerCase(Locale.ROOT); + + if (sql.contains("idempotency_key") && !sql.contains("custom_idempotency_distinctor")) { + keyOnly.add(method.getName() + ": " + query.value().strip()); + } + } else if (method.getName().contains("IdempotencyKey") && !method.getName().contains("CustomIdempotencyDistinctor")) { + keyOnly.add(method.getName()); + } + } + + assertThat(keyOnly).as("These repository methods look a command up by its idempotency key without its distinctor. Add " + + "custom_idempotency_distinctor to the query, or AndCustomIdempotencyDistinctor to the derived finder.").isEmpty(); + } + + @Test + void everyStoreMethodTakingAKeyAlsoTakesTheDistinctor() { + var keyOnly = new ArrayList(); + + for (Method method : CommandStore.class.getDeclaredMethods()) { + var names = Arrays.stream(method.getParameters()).map(Parameter::getName).toList(); + + assertThat(Arrays.stream(method.getParameters()).allMatch(Parameter::isNamePresent)) + .as("Parameter names must be compiled in (-parameters) for this check to mean anything.").isTrue(); + + if (names.contains("key") && !names.contains("distinctor")) { + keyOnly.add(method.getName() + names); + } + } + + assertThat(keyOnly).as("These store methods take an idempotency key without its distinctor, so they cannot tell apart the " + + "commands sharing that key.").isEmpty(); + } +} diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java index 2cb53d6388e..d133d13f082 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java @@ -82,13 +82,13 @@ void claimingAKeyIsRetriedWhenItLosesToContention() { @Test void recordingTheAnswerIsRetried() { - when(repository.updateResponse(anyString(), anyInt(), any())).thenThrow(new ConcurrencyFailureException("contention")); + when(repository.updateResponse(anyString(), anyString(), anyInt(), any())).thenThrow(new ConcurrencyFailureException("contention")); contextRunner.run(context -> { var store = context.getBean(CommandStore.class); - assertThat(catchFailure(() -> store.recordResponse("a-key", 400, "{}"))).isInstanceOf(ConcurrencyFailureException.class); - verify(repository, times(MAX_ATTEMPTS)).updateResponse(anyString(), anyInt(), any()); + assertThat(catchFailure(() -> store.recordResponse("a-key", "", 400, "{}"))).isInstanceOf(ConcurrencyFailureException.class); + verify(repository, times(MAX_ATTEMPTS)).updateResponse(anyString(), anyString(), anyInt(), any()); }); } diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java index db94620fd37..f9cb9f5f779 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -70,7 +70,7 @@ public void aStoredResponseIsReplayedAsTheObjectTheCommandProduced() { store.store(processed(key, "hello")); - var replayed = store.getReplayByKey(key).response(); + var replayed = store.getReplayByKey(key, "").response(); assertNotNull(replayed, "A processed command should replay its stored response."); assertInstanceOf(DummyResponse.class, replayed, "The response is rehydrated to its own type, not handed back as text."); @@ -83,14 +83,14 @@ public void onlyAnIdenticalRequestMatchesTheStoredOne() { store.store(processed(key, "hello")); - assertTrue(store.matchesStoredRequest(key, DummyRequest.builder().content("hello").build()), + assertTrue(store.matchesStoredRequest(key, "", DummyRequest.builder().content("hello").build()), "The same request must match the stored one."); - assertFalse(store.matchesStoredRequest(key, DummyRequest.builder().content("goodbye").build()), + assertFalse(store.matchesStoredRequest(key, "", DummyRequest.builder().content("goodbye").build()), "A different request of the same type must not match; it would replay an unrelated response."); - assertFalse(store.matchesStoredRequest(key, DummyResponse.builder().content("hello").build()), + assertFalse(store.matchesStoredRequest(key, "", DummyResponse.builder().content("hello").build()), "A different request type must not match."); - assertFalse(store.matchesStoredRequest(key, null), "A null payload must not match."); - assertFalse(store.matchesStoredRequest(UUID.randomUUID().toString(), DummyRequest.builder().content("hello").build()), + assertFalse(store.matchesStoredRequest(key, "", null), "A null payload must not match."); + assertFalse(store.matchesStoredRequest(UUID.randomUUID().toString(), "", DummyRequest.builder().content("hello").build()), "An unknown idempotency key must not match anything."); } @@ -103,7 +103,7 @@ public void anIdenticalRetryIsRecognisedWhateverTypesTheRequestCarries() { store.claim(command); - assertTrue(store.matchesStoredRequest(key, fullyPopulated()), + assertTrue(store.matchesStoredRequest(key, "", fullyPopulated()), "An identical retry must be recognised whatever field types the request carries."); } @@ -116,27 +116,27 @@ public void aChangeToAnyFieldMakesItADifferentRequest() { store.claim(command); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().content("other").build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().content("other").build()), "A different string must not be replayed."); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().referenceId(8L).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().referenceId(8L).build()), "A different id must not be replayed."); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().count(2).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().count(2).build()), "A different whole number must not be replayed."); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().flag(false).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().flag(false).build()), "A different flag must not be replayed."); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().amount(new BigDecimal("150.00")).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().amount(new BigDecimal("150.00")).build()), "A different amount must not be replayed."); - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().businessDate(LocalDate.of(2026, 10, 6)).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().businessDate(LocalDate.of(2026, 10, 6)).build()), "A different date must not be replayed."); // one nanosecond apart, which also shows whether sub-second precision survives being stored assertFalse( - store.matchesStoredRequest(key, + store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().timestamp(OffsetDateTime.parse("2026-10-05T11:22:33.123456788Z")).build()), "A different timestamp must not be replayed."); // the case a comparison through a double would miss: a difference past the 17th significant digit assertFalse( - store.matchesStoredRequest(key, + store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().preciseAmount(new BigDecimal("12345678901234567890.12345678902")).build()), "Two amounts that differ beyond a double's precision are different requests."); } @@ -151,7 +151,7 @@ public void aDecimalKeepsItsScaleWhenComparedAgainstAStoredRequest() { store.claim(command); // 1.50 and 1.5 are the same number but not the same request body, and the conservative answer is the safe one - assertFalse(store.matchesStoredRequest(key, fullyPopulated().toBuilder().amount(new BigDecimal("100.0")).build()), + assertFalse(store.matchesStoredRequest(key, "", fullyPopulated().toBuilder().amount(new BigDecimal("100.0")).build()), "An amount written with a different scale must not be taken for the stored one."); } @@ -162,11 +162,83 @@ public void claimSucceedsOnceAndSetsTheCommandId() { assertTrue(store.claim(first), "The first claim of an idempotency key should succeed."); assertNotNull(first.getCommandId(), "A successful claim should assign the command id."); - assertTrue(store.existsByKey(key), "A claimed key should be visible to other requests immediately."); + assertTrue(store.existsByKey(key, ""), "A claimed key should be visible to other requests immediately."); assertFalse(store.claim(command(key, "hello")), "A second claim of the same idempotency key should fail."); } + @Test + public void aClaimIsAlwaysStoredWithItsTime() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + // as when the timestamp hook is switched off + command.setCreatedAt(null); + + assertTrue(store.claim(command)); + assertNotNull(command.getCreatedAt(), "The claim time must be kept on the command, so the audit hooks write it back."); + assertNotNull(store.getReplayByKey(key, "").claimedAt(), + "Without a claim time an abandoned claim can never be told from a running one, and is answered 425 for ever."); + } + + @Test + public void aKeyIsUniqueTogetherWithItsDistinctor() { + var key = UUID.randomUUID().toString(); + var loan = command(key, "hello"); + var client = command(key, "hello"); + var loanAgain = command(key, "hello"); + + loan.setCustomIdempotencyDistinctor("LOAN|CREATE"); + client.setCustomIdempotencyDistinctor("CLIENT|CREATE"); + loanAgain.setCustomIdempotencyDistinctor("LOAN|CREATE"); + + assertTrue(store.claim(loan), "The first claim of a key under a distinctor should succeed."); + assertTrue(store.claim(client), "The same key under another distinctor is a different command."); + assertFalse(store.claim(loanAgain), "The same key under the same distinctor is a repeat."); + + assertTrue(store.existsByKey(key, "LOAN|CREATE")); + assertTrue(store.existsByKey(key, "CLIENT|CREATE")); + assertFalse(store.existsByKey(key, ""), "A key claimed only under distinctors is not claimed under none."); + } + + @Test + public void aRepeatIsAnsweredFromTheRowWithItsOwnDistinctor() { + var key = UUID.randomUUID().toString(); + var loan = processed(key, "loan"); + var client = command(key, "client"); + + loan.getCommand().setCustomIdempotencyDistinctor("LOAN|CREATE"); + client.setCustomIdempotencyDistinctor("CLIENT|CREATE"); + + store.claim(loan.getCommand()); + store.store(loan); + store.claim(client); + store.recordResponse(key, "CLIENT|CREATE", 400, "{\"error\":\"bad request\"}"); + + assertEquals(PROCESSED, store.getReplayByKey(key, "LOAN|CREATE").state()); + assertEquals("LOAN", ((DummyResponse) store.getReplayByKey(key, "LOAN|CREATE").response()).getContent()); + assertNull(store.getReplayByKey(key, "LOAN|CREATE").statusCode(), "Recording the other row's answer must not touch this one."); + + assertEquals(UNDER_PROCESSING, store.getReplayByKey(key, "CLIENT|CREATE").state()); + assertEquals(400, store.getReplayByKey(key, "CLIENT|CREATE").statusCode()); + + assertTrue(store.matchesStoredRequest(key, "LOAN|CREATE", DummyRequest.builder().content("loan").build())); + assertFalse(store.matchesStoredRequest(key, "LOAN|CREATE", DummyRequest.builder().content("client").build()), + "A request is compared only with the request stored under the same distinctor."); + assertEquals(UNKNOWN, store.getReplayByKey(key, "").state(), "No row was stored under the empty distinctor."); + } + + @Test + public void aCommandWithNoDistinctorIsStoredWithTheEmptyOne() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + command.setCustomIdempotencyDistinctor(null); + + assertTrue(store.claim(command), "The column does not take null, so a missing distinctor has to be stored as empty."); + assertEquals("", store.getByKey(key, "").getCustomIdempotencyDistinctor()); + } + @Test public void commandsWithoutAKeyNeverConflict() { assertTrue(store.claim(command(null, "hello")), "A command without an idempotency key should always be claimable."); @@ -199,8 +271,10 @@ public void onlyOneConcurrentClaimOfTheSameKeyWins() throws Exception { } assertEquals(1, winners.get(), "Exactly one concurrent request may claim a key; the rest must be told to stand down."); - assertEquals(1, repository.findAll().stream().filter(e -> key.equals(e.getIdempotencyKey())).count(), - "Only one command row may exist per idempotency key."); + assertEquals(1, + repository.findAll().stream() + .filter(e -> key.equals(e.getIdempotencyKey()) && "".equals(e.getCustomIdempotencyDistinctor())).count(), + "Only one command row may exist per idempotency key and distinctor."); } @Test @@ -208,11 +282,11 @@ public void theStateOfAKeyTellsAnInFlightCommandFromAFinishedOne() { var key = UUID.randomUUID().toString(); var command = command(key, "hello"); - assertEquals(UNKNOWN, store.getReplayByKey(key).state(), "An unclaimed key has no state."); + assertEquals(UNKNOWN, store.getReplayByKey(key, "").state(), "An unclaimed key has no state."); store.claim(command); - var inFlight = store.getReplayByKey(key); + var inFlight = store.getReplayByKey(key, ""); assertEquals(UNDER_PROCESSING, inFlight.state(), "A claimed key should report the command as in flight."); assertNotNull(inFlight.claimedAt(), "When the key was claimed is what tells a slow command from an abandoned one."); assertNull(inFlight.statusCode(), "An in-flight command has not been answered yet."); @@ -220,9 +294,9 @@ public void theStateOfAKeyTellsAnInFlightCommandFromAFinishedOne() { store.store(CommandContext.builder().command(command) .response(DummyResponse.builder().content("HELLO").build()).state(PROCESSED).build()); - store.recordResponse(key, 201, null); + store.recordResponse(key, "", 201, null); - var processed = store.getReplayByKey(key); + var processed = store.getReplayByKey(key, ""); assertEquals(PROCESSED, processed.state(), "A completed command should report as processed."); assertEquals("HELLO", ((DummyResponse) processed.response()).getContent(), "The result the original command produced must be replayable."); @@ -238,9 +312,9 @@ public void aFailedCommandReportsAsFailedRatherThanAsMissing() { store.claim(command); store.store(CommandContext.builder().command(command).state(ERROR).build()); // a failed command produces no result of its own, so the error document the client got is what fills the gap - store.recordResponse(key, 400, "{\"error\":\"bad request\"}"); + store.recordResponse(key, "", 400, "{\"error\":\"bad request\"}"); - var failed = store.getReplayByKey(key); + var failed = store.getReplayByKey(key, ""); assertEquals(ERROR, failed.state(), "A failed command should report as failed."); assertEquals(400, failed.statusCode(), "The status the failure was answered with must be replayable."); assertEquals("{\"error\":\"bad request\"}", failed.response(), @@ -253,9 +327,9 @@ public void nothingIsCapturedForACommandThatStoredItsOwnResult() { store.store(processed(key, "hello")); - store.recordResponse(key, 200, "{\"content\":\"CAPTURED\"}"); + store.recordResponse(key, "", 200, "{\"content\":\"CAPTURED\"}"); - var replay = store.getReplayByKey(key); + var replay = store.getReplayByKey(key, ""); assertInstanceOf(DummyResponse.class, replay.response(), "A repeat is answered from the command's own result."); assertEquals("HELLO", ((DummyResponse) replay.response()).getContent()); @@ -276,9 +350,9 @@ public void aCapturedAnswerIsReplayedByteForByteWhenThereIsNoResultToRehydrate() "nested":{"inner":0.100},"list":[1.10,2.20]}"""; store.claim(command(key, "hello")); - store.recordResponse(key, 200, answer); + store.recordResponse(key, "", 200, answer); - assertEquals(answer, store.getReplayByKey(key).response(), + assertEquals(answer, store.getReplayByKey(key, "").response(), "A captured answer must replay exactly as the client was sent it, byte for byte."); } @@ -288,12 +362,12 @@ public void storingTheCommandDoesNotResetTheRecordedStatus() { var command = command(key, "hello"); store.claim(command); - store.recordResponse(key, 400, "{\"error\":\"bad request\"}"); + store.recordResponse(key, "", 400, "{\"error\":\"bad request\"}"); // the audit hooks rebuild the row from the command, which has no notion of the status the client was sent store.store(CommandContext.builder().command(command).state(ERROR).build()); - assertEquals(400, store.getReplayByKey(key).statusCode(), "A full-row save must not wipe the recorded status."); + assertEquals(400, store.getReplayByKey(key, "").statusCode(), "A full-row save must not wipe the recorded status."); } @Test @@ -302,7 +376,7 @@ public void theCommandRecordsWhatItActedOnAndWhatItDid() { store.claim(command(key, "hello")); - var claimed = repository.findOneByIdempotencyKey(key).orElseThrow(); + var claimed = repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "").orElseThrow(); // the names an audit search and a checker inbox look a command up by, and from which the approval permission // is derived; a row without them is invisible to both diff --git a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml index e3cc0c19edd..6b22baa064c 100644 --- a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml +++ b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml @@ -73,5 +73,6 @@ + diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java index db88938890e..1e66d0d00b1 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java @@ -35,6 +35,13 @@ public abstract class Command implements Serializable { private String idempotencyKey; + /** + * What {@link #idempotencyKey} is unique together with: a command row is unique on the pair, and a repeat is + * matched only against the row with the same key and the same distinctor. Set when the key is claimed; the empty + * string, the column's default, when nothing distinguishes it - including for a command that carries no key at all. + */ + private String customIdempotencyDistinctor = ""; + private String ipAddress; private Instant createdAt; @@ -73,6 +80,14 @@ public abstract class Command implements Serializable { */ public abstract String entityName(); + /** + * The column is {@code NOT NULL}, and an absent distinctor means "none", so {@code null} is stored as the empty + * string rather than rejected by the database. + */ + public void setCustomIdempotencyDistinctor(String customIdempotencyDistinctor) { + this.customIdempotencyDistinctor = customIdempotencyDistinctor == null ? "" : customIdempotencyDistinctor; + } + /** The action this command performs on {@link #entityName()}, again as {@code m_permission} spells it. */ public abstract String actionName(); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java index 8a6d831af64..db98633b4de 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java @@ -22,9 +22,14 @@ public interface CommandStore { Command getById(Long id); - Command getByKey(String key); + /* + * An idempotency key is unique together with a distinctor (see Command#getCustomIdempotencyDistinctor()), so every + * lookup by key takes both: the same key may exist once per distinctor. + */ + + Command getByKey(String key, String distinctor); - boolean existsByKey(String key); + boolean existsByKey(String key, String distinctor); /** * @return everything needed to answer a repeated request exactly as the original one was answered - the state, and @@ -32,18 +37,19 @@ public interface CommandStore { * that failed cannot be answered the same way, so the caller has to be able to tell them apart. Never * {@code null}; an unknown key reports {@link CommandState#UNKNOWN}. */ - CommandReplay getReplayByKey(String key); + CommandReplay getReplayByKey(String key, String distinctor); /** * Records what the original request was answered with, for the parts a command cannot know: the status code always, * and the body only when the command stored no result of its own. A stored result is never replaced, because a * replay is rendered from that result rather than from captured text. */ - void recordResponse(String key, int statusCode, String body); + void recordResponse(String key, String distinctor, int statusCode, String body); /** - * Atomically claims the command's idempotency key by persisting it, so that no other request can execute a command - * under the same key. Must not be retried, and the conflict must not be swallowed. + * Atomically claims the command's idempotency key, together with its distinctor, by persisting it, so that no other + * request can execute a command under the same key and distinctor. Must not be retried, and the conflict must not + * be swallowed. * * @return {@code true} if the key was claimed by this call, {@code false} if it was already claimed */ @@ -54,7 +60,7 @@ public interface CommandStore { * Comparing the whole request, not just its type, is what stops a key reused for a different request from * replaying an unrelated response. */ - boolean matchesStoredRequest(String key, Object payload); + boolean matchesStoredRequest(String key, String distinctor, Object payload); void store(CommandContext ctx); } diff --git a/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc index 4545d825376..e3a4d0dc115 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc @@ -77,6 +77,10 @@ execution that never happened. | `idempotency_key` | The key the command was claimed under. See the idempotency chapter. +| `custom_idempotency_distinctor` +| What the key is unique together with, computed when the key was claimed. The empty string when nothing distinguishes +it, including for a command without a key. See the idempotency chapter. + | `response_status_code` | Only set for a command that produced no result of its own. See the idempotency chapter. |=== @@ -132,5 +136,9 @@ auditing disabled refuses to start, naming the properties that conflict. Were it under a key would be answered normally, its record would stay `UNDER_PROCESSING` for ever, and every repeat of that key would be answered `425 Too Early` - a failure that only appears on the second request and never resolves. +The same holds for the after and error hooks individually: with idempotency enabled, switching off +`fineract.command.audit.hook-post-enabled` or `fineract.command.audit.hook-error-enabled` also refuses to start. The +before hook can be switched off, because claiming the key writes the record it would otherwise write. + The reverse is fine and is a supported arrangement: auditing without idempotency records every command as usual, reads no idempotency key, and executes a repeated request again rather than replaying it. diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index 95f35885101..c2e46e5d67f 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -40,8 +40,9 @@ In batch requests, you can set the idempotency key for every batch item, in the The new command processing implements idempotency as command hooks, in the `fineract-command-idempotency` module. It answers a repeated request the same way the legacy processing does - the same `x-served-from-cache` header, the -same `425 Too Early` while the original is still running, the same status and body once it has finished - with one -deliberate difference described under <>. +same `425 Too Early` while the original is still running, the same status and body once it has finished. By default +a key is scoped the way the legacy processing scopes it; see <> for the stricter +alternative. === Configuration @@ -55,6 +56,7 @@ fineract.command.idempotency.key-header-name=Idempotency-Key fineract.command.idempotency.hook-key-header-pre=true fineract.command.idempotency.hook-check-pre=true fineract.command.idempotency.claim-timeout=10m +fineract.command.idempotency.custom-distinctor=ENTITY_NAME_AND_ACTION_NAME ---- The key is read from the HTTP header only. It is deliberately not read from a query parameter, because keys in query @@ -110,7 +112,8 @@ that never happened. | Completed, but its stored result cannot be reconstructed | `409 Conflict`, saying so. The key has been used and its answer can no longer be produced - reporting a server error -would say the request failed, and an empty body would say it succeeded with nothing to return. Neither is true. +would say the request failed, and an empty body would say it succeeded with nothing to return. Neither is true. Only a +command that completed stores a result, so the command did take effect: it must not be sent again under a new key. | Any other state, or a key used for a different request | `409 Conflict`. @@ -118,12 +121,32 @@ would say the request failed, and an empty body would say it succeeded with noth === Scope of an idempotency key -An idempotency key is unique per tenant across all commands. +An idempotency key is unique together with a _distinctor_: a value computed from the command when its key is claimed +and stored beside the key in `m_command.custom_idempotency_distinctor`. The command record is unique on the pair, and a +repeat is matched - and replayed - only against the record with the same key and the same distinctor. +`fineract.command.idempotency.custom-distinctor` chooses how the distinctor is computed: -IMPORTANT: This differs from the legacy command processing, where a key is scoped by action and entity name, so the -same key could be used on two different endpoints. Under the new processing the second of those requests is rejected -with `409 Conflict` rather than executed. Clients that derive the key from something reused across calls, such as a -correlation id, have to send a distinct key per request. +[cols="1,2,3"] +|=== +| Value | Distinctor | Scope of a key + +| `ENTITY_NAME_AND_ACTION_NAME` (default) +| `EntityAndActionNameCustomIdempotencyDistinctor`: the command's entity name and action name, as `m_permission` spells +them, joined with `\|` - for example `LOAN\|CREATE`. +| Unique per tenant, entity and action, the way the legacy command processing scopes a key. + +| `NONE` +| `NoCustomIdempotencyDistinctor`: always the empty string. +| Unique per tenant across all commands. +|=== + +An application can replace the distinctor altogether by defining its own `CustomIdempotencyDistinctor` bean. Its value +must be the same for every repeat of a request, must not be `null` and must fit the 255-character column; a value that +does not is refused before the key is claimed. + +IMPORTANT: Under `NONE` the new processing is stricter than the legacy one: the same key sent to two different +endpoints is rejected with `409 Conflict` for the second rather than executed. Clients that derive the key from +something reused across calls, such as a correlation id, then have to send a distinct key per request. A repeat is also only replayed when it carries the same request as the original. A key reused for the same endpoint with a different body is rejected with `409 Conflict` instead of being answered with the earlier result, which would @@ -136,6 +159,18 @@ move a command out of `UNDER_PROCESSING` and store what it produced. Idempotency auditing, and an application configured with idempotency enabled and `fineract.command.audit.enabled=false` refuses to start rather than failing later in a way that only shows up on a client's second request. +The same applies to the two audit hooks that record how a command finished, which can be switched off on their own: +with idempotency enabled, `fineract.command.audit.hook-post-enabled=false` (nothing records a completed command) or +`fineract.command.audit.hook-error-enabled=false` (nothing records a failed one) also refuses to start. The before hook +is not required, because claiming the key has already written the record it would write. + +The claim is always stored with the time it was made, which is what <> measures. It is +taken from the timestamp hook when that is on, and from the moment of the claim when it is not. + +Every result type a command handler returns has to be readable back from the store, since a repeat is answered by +reading it back. A test walks every handler on the classpath and fails for a result type Jackson cannot construct, such +as a Lombok `@Builder` class without `@NoArgsConstructor` and `@AllArgsConstructor`. + See the command auditing chapter for what is recorded and when. === Reliability diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java index aadf3498a09..2f9c12e0fe8 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralCreateResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java index 5422ea7bf1c..5bd70d065ad 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java index dd0ea35389e..8e4da26359a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java @@ -21,11 +21,15 @@ import java.io.Serial; import java.io.Serializable; import java.math.BigDecimal; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralUpdateResponse implements Serializable { @Serial @@ -39,6 +43,8 @@ public class ClientCollateralUpdateResponse implements Serializable { @Data @Builder + @NoArgsConstructor + @AllArgsConstructor public static class Changes implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java index f6f087c2698..5835dc6b823 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductCreateResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java index e7df5b7580c..2d919008aef 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java index 2ab854b1dc9..f466f4ffe65 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java @@ -22,11 +22,15 @@ import java.io.Serial; import java.io.Serializable; import java.math.BigDecimal; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductUpdateResponse implements Serializable { @Serial @@ -38,6 +42,8 @@ public class CollateralProductUpdateResponse implements Serializable { @Data @Builder + @NoArgsConstructor + @AllArgsConstructor @Schema(name = "CollateralProductUpdateChanges") public static class Changes implements Serializable { diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java index 78c6cdaa742..52e00e02d36 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class LoanCollateralDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index eb17c3c3237..d3ded10e206 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -960,6 +960,10 @@ fineract.command.idempotency.hook-check-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_ # otherwise answer 425 for ever. The key is never re-executed, only refused, so set it comfortably above the # slowest command rather than tightly. fineract.command.idempotency.claim-timeout=${FINERACT_COMMAND_IDEMPOTENCY_CLAIM_TIMEOUT:10m} +# What an idempotency key is unique together with. ENTITY_NAME_AND_ACTION_NAME (default): the command's entity and +# action names joined with "|" (for example LOAN|CREATE), so a key may be used once per entity and action, the way the +# legacy command processing scopes it. NONE: nothing, so a key is unique per tenant across all commands. +fineract.command.idempotency.custom-distinctor=${FINERACT_COMMAND_IDEMPOTENCY_CUSTOM_DISTINCTOR:ENTITY_NAME_AND_ACTION_NAME} # Fineract Default Config values fineract.defaults.office-id=${FINERACT_CONFIG_DEFAULT_OFFICE_ID:1} diff --git a/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java new file mode 100644 index 00000000000..bbfa0745573 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java @@ -0,0 +1,194 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; +import static org.assertj.core.api.Assertions.assertThat; + +import com.fasterxml.jackson.annotation.JsonProperty; +import java.lang.reflect.Field; +import java.lang.reflect.Modifier; +import java.lang.reflect.ParameterizedType; +import java.lang.reflect.Type; +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import org.apache.fineract.command.core.CommandHandler; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; +import org.apache.fineract.infrastructure.core.jackson3.Jackson3ObjectMapperConfig; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.config.BeanDefinition; +import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider; +import org.springframework.core.ResolvableType; +import org.springframework.core.type.filter.AssignableTypeFilter; +import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.node.ObjectNode; +import tools.jackson.databind.node.StringNode; + +/** + * Holds every command handler's result to being readable back from the command store. + * + *

+ * A repeat of an idempotency key is answered by reading the stored result back into the object the handler returned and + * handing it to the web layer again. A result type Jackson cannot construct - one with a builder but no constructor it + * can use, say - stores fine and fails only when a client repeats the request, which is then refused with {@code 409} + * instead of being given its answer. Nothing else notices: the first request succeeds, and every test that does not + * repeat a request passes. + * + *

+ * This walks every {@link CommandHandler} on the classpath, builds a stored row for its result type with every nested + * object present, and reads it back through the mapper the command store uses. + */ +class CommandHandlerResultRehydrationTest { + + /** The sample handlers that exist to exercise the framework; they are not commands the application serves. */ + private static final String SAMPLE_HANDLERS = "org.apache.fineract.command.test"; + + private static final String FINERACT_PACKAGE = "org.apache.fineract"; + + private final ObjectMapper mapper = new Jackson3ObjectMapperConfig().jackson3ObjectMapper(); + + private final JsonCommandMapper commandJsonMapper = new JsonCommandMapper(mapper); + + @Test + void everyCommandResultCanBeReadBackForAReplay() { + var unreadable = new ArrayList(); + + for (Class handler : commandHandlers()) { + if (handler.getName().startsWith(SAMPLE_HANDLERS)) { + continue; + } + + var result = ResolvableType.forClass(handler).as(CommandHandler.class).getGeneric(1).resolve(); + + if (result == null || Void.class.equals(result)) { + continue; + } + + var stored = storedRow(result, new HashSet<>()); + + stored.set(COMMAND_JSON_CLASS_ATTRIBUTE, new StringNode(result.getCanonicalName())); + + try { + assertThat((Object) commandJsonMapper.map(stored)).isInstanceOf(result); + } catch (RuntimeException | AssertionError e) { + unreadable.add(handler.getSimpleName() + " -> " + result.getSimpleName() + ": " + rootMessage(e)); + } + } + + assertThat(unreadable).as("These command results cannot be read back from the command store, so a repeat of the request is " + + "refused with 409 instead of being given its answer. Give the type, and every type nested in it, a " + + "constructor Jackson can use - for a Lombok @Builder that means adding @NoArgsConstructor and " + "@AllArgsConstructor.") + .isEmpty(); + } + + /** + * A stored row with every nested Fineract type present as an object, so that each one has to be constructed too. + * Scalars are left out: they never need a constructor, and their formats are covered by the wire-format tests. + */ + private ObjectNode storedRow(Class type, Set> visiting) { + var node = mapper.createObjectNode(); + + if (!visiting.add(type)) { + return node; + } + + for (var current = type; current != null && !Object.class.equals(current); current = current.getSuperclass()) { + for (Field field : current.getDeclaredFields()) { + if (Modifier.isStatic(field.getModifiers()) || field.isSynthetic()) { + continue; + } + + var name = propertyName(field); + var nested = nestedType(field.getType()); + + if (nested != null) { + node.set(name, storedRow(nested, visiting)); + } else if (Collection.class.isAssignableFrom(field.getType())) { + var element = nestedType(elementType(field.getGenericType())); + + if (element != null) { + node.putArray(name).add(storedRow(element, visiting)); + } + } + } + } + + visiting.remove(type); + + return node; + } + + private static String propertyName(Field field) { + var property = field.getAnnotation(JsonProperty.class); + + return property != null && !property.value().isEmpty() ? property.value() : field.getName(); + } + + private static Class nestedType(Class type) { + if (type == null || type.isEnum() || type.isInterface() || type.isPrimitive() || !type.getName().startsWith(FINERACT_PACKAGE)) { + return null; + } + + return type; + } + + private static Class elementType(Type type) { + if (type instanceof ParameterizedType parameterized && parameterized.getActualTypeArguments().length == 1 + && parameterized.getActualTypeArguments()[0] instanceof Class element) { + return element; + } + + return null; + } + + private static String rootMessage(Throwable t) { + var root = t; + + while (root.getCause() != null) { + root = root.getCause(); + } + + var message = root.getMessage(); + + return message == null ? root.getClass().getSimpleName() : message.lines().findFirst().orElse(message); + } + + private static List> commandHandlers() { + var scanner = new ClassPathScanningCandidateComponentProvider(false); + + scanner.addIncludeFilter(new AssignableTypeFilter(CommandHandler.class)); + + var found = new ArrayList>(); + + for (BeanDefinition definition : scanner.findCandidateComponents(FINERACT_PACKAGE)) { + try { + found.add(Class.forName(definition.getBeanClassName())); + } catch (ClassNotFoundException e) { + throw new IllegalStateException("Scanned a handler that cannot be loaded: " + definition.getBeanClassName(), e); + } + } + + assertThat(found).as("The scan must actually find the handlers, or this test passes by finding nothing.").isNotEmpty(); + + return found; + } +} From 5ed8e15ebf0b9d42680f35a017d43867dafca86b Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 17:56:54 +0000 Subject: [PATCH 10/11] FINERACT-2485: Release the idempotency key of a recoverably failed command The legacy command processing lets a retry under the same key execute again after a recoverable failure (FINERACT-2985): an exception marked RecoverableError, or one whose error codes are all in the idempotency-recoverable-error-codes global configuration. The new command processing replayed every failure for ever, so a client retrying a transient failure on a migrated endpoint could not get past it. A command that fails recoverably now moves its record to _RE, the scheme the legacy processing uses, hashing a key too long to take the suffix. The original key is free, so the retry is executed as a new command, and the failure stays on record under the moved key with the answer the client was sent. If the moved key is taken or the move fails, the failure stays under the original key, as for any other failure. The decision sits behind RecoverableCommandErrorClassifier in fineract-command, so the command modules stay independent of fineract-core; fineract-core supplies an adapter that delegates to the legacy RecoverableErrorClassifier. Without a classifier, nothing is recoverable. The key is moved on the command before the audit error hook runs, because that hook rewrites the whole row from the command. --- .../IdempotencyCommandConstants.java | 2 + .../idempotency/RecoverableErrorKey.java | 64 +++++++ ...dempotencyRecoverableErrorCommandHook.java | 124 ++++++++++++++ .../IdempotencyCommandAutoConfiguration.java | 11 ++ ...empotencyRecoverableErrorEndToEndTest.java | 139 ++++++++++++++++ .../idempotency/RecoverableErrorKeyTest.java | 49 ++++++ ...otencyRecoverableErrorCommandHookTest.java | 156 ++++++++++++++++++ .../RecoverableCommandErrorClassifier.java | 39 +++++ ...overableCommandErrorClassifierAdapter.java | 41 +++++ ...ableCommandErrorClassifierAdapterTest.java | 52 ++++++ .../en/chapters/architecture/idempotency.adoc | 19 ++- 11 files changed, 695 insertions(+), 1 deletion(-) create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java create mode 100644 fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java create mode 100644 fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java create mode 100644 fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java create mode 100644 fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java create mode 100644 fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java index f1d1efa0186..54441d7cb17 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandConstants.java @@ -42,4 +42,6 @@ private IdempotencyCommandConstants() {} + ".custom-distinctor"; public static final int COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE = 20; public static final int COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE = 21; + /** Before the audit error hook (30), which writes the row with whatever key the command then carries. */ + public static final int COMMAND_IDEMPOTENCY_HOOK_RECOVERABLE_ERROR = 22; } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java new file mode 100644 index 00000000000..a4c6cf3a270 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java @@ -0,0 +1,64 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.HexFormat; + +/** + * The key a failed command is moved to when its failure is recoverable, so that its original key is free for a retry. + * + *

+ * The same scheme the legacy command processing uses: {@code _RE}, where {@code } is the command's own row + * id, so the moved key is unique and still traceable to the original. When that would not fit the column, the key part + * is replaced by the first {@value #HASH_LENGTH} hex characters of its SHA-256 hash, which always fits. + */ +public final class RecoverableErrorKey { + + public static final String SUFFIX = "_RE"; + + /** The width of {@code m_command.idempotency_key}. */ + public static final int KEY_LENGTH = 255; + + static final int HASH_LENGTH = 40; + + private RecoverableErrorKey() {} + + public static String movedKey(String idempotencyKey, long commandId) { + var suffix = SUFFIX + commandId; + + if (idempotencyKey.length() + suffix.length() <= KEY_LENGTH) { + return idempotencyKey + suffix; + } + + return hash(idempotencyKey) + suffix; + } + + private static String hash(String idempotencyKey) { + try { + var digest = MessageDigest.getInstance("SHA-256").digest(idempotencyKey.getBytes(StandardCharsets.UTF_8)); + + return HexFormat.of().formatHex(digest).substring(0, HASH_LENGTH); + } catch (NoSuchAlgorithmException e) { + throw new IllegalStateException("SHA-256 is not available", e); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java new file mode 100644 index 00000000000..1b6cc39461a --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java @@ -0,0 +1,124 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_RECOVERABLE_ERROR; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; + +import java.util.concurrent.CompletionException; +import java.util.concurrent.ExecutionException; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookError; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.apache.fineract.command.idempotency.RecoverableErrorKey; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.context.request.RequestAttributes; +import org.springframework.web.context.request.RequestContextHolder; + +/** + * Releases the idempotency key of a command that failed recoverably, so that a retry under the same key executes the + * command again instead of being answered with the failure. + * + *

+ * The failure is not discarded: the command is moved to {@code _RE} (see {@link RecoverableErrorKey}) and the + * audit error hook, which runs after this one, records it there - outcome, error and the answer the client was sent. + * Moving it is done by changing the key on the command, because the audit hook rewrites the whole row from the command; + * changing only the row would be undone a moment later. + * + *

+ * Anything that goes wrong here leaves the key where it is, which is what happens to every other failure: the retry is + * answered with the stored failure. Failing the request over it would replace the error the client needs to see. + */ +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_RECOVERABLE_ERROR) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) +final class IdempotencyRecoverableErrorCommandHook implements CommandHookError { + + private final CommandStore store; + + private final RecoverableCommandErrorClassifier classifier; + + @Override + public void onError(CommandContext ctx) { + var command = ctx.getCommand(); + var key = command.getIdempotencyKey(); + + // a repeat that was refused never claimed the key, and a command without a key or a row has nothing to release + if (ctx.isSkipExecution() || StringUtils.isEmpty(key) || command.getCommandId() == null) { + return; + } + + try { + if (!classifier.isRecoverable(unwrap(ctx.getError()))) { + return; + } + + var distinctor = command.getCustomIdempotencyDistinctor(); + var movedKey = RecoverableErrorKey.movedKey(key, command.getCommandId()); + + if (store.existsByKey(movedKey, distinctor)) { + // only possible when a client sent that exact key itself; storing the failure under the original key + // is the same thing the legacy processing does then + log.warn("Idempotency key {} is already taken, keeping the recoverable failure under the original key {}", movedKey, key); + + return; + } + + command.setIdempotencyKey(movedKey); + rememberMovedKeyForResponseCapture(key, movedKey); + + log.info("Command {} failed recoverably; idempotency key {} is released and the failure is kept under {}", + command.getCommandId(), key, movedKey); + } catch (RuntimeException e) { + command.setIdempotencyKey(key); + + log.warn("Could not release idempotency key {} after a recoverable error, keeping the failure under it", key, e); + } + } + + /** The dispatchers that run commands elsewhere hand the failure back wrapped. */ + private static Throwable unwrap(Throwable error) { + var current = error; + + while ((current instanceof CompletionException || current instanceof ExecutionException) && current.getCause() != null) { + current = current.getCause(); + } + + return current; + } + + /** The response capture filter records the answer against the claimed key, which is now the moved one. */ + private static void rememberMovedKeyForResponseCapture(String key, String movedKey) { + var attributes = RequestContextHolder.getRequestAttributes(); + + if (attributes != null + && key.equals(attributes.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, RequestAttributes.SCOPE_REQUEST))) { + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, movedKey, RequestAttributes.SCOPE_REQUEST); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java index f5ebec06614..439125379ea 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java @@ -24,6 +24,7 @@ import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE; import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; import org.apache.fineract.command.idempotency.web.IdempotencyResponseCaptureFilter; @@ -68,4 +69,14 @@ FilterRegistrationBean idempotencyResponseCapt CustomIdempotencyDistinctor customIdempotencyDistinctor(IdempotencyCommandProperties properties) { return properties.getCustomDistinctor().create(); } + + /** + * Treats no failure as recoverable, so every failure keeps its key, until the application says otherwise by + * defining its own classifier - Fineract does, with the rules of the legacy command processing. + */ + @Bean + @ConditionalOnMissingBean + RecoverableCommandErrorClassifier recoverableCommandErrorClassifier() { + return error -> false; + } } diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java new file mode 100644 index 00000000000..d81d5b42a42 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java @@ -0,0 +1,139 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.apache.fineract.command.jdbc.store.domain.CommandEntity; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.apache.fineract.command.test.sample.exception.DummyException; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, with the sample command's failure classified as recoverable: a + * retry under the same key has to be executed again rather than answered with the stored failure, and the failure has + * to stay on record. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = { TestConfiguration.class, IdempotencyRecoverableErrorEndToEndTest.RecoverableDummyFailures.class }) +public class IdempotencyRecoverableErrorEndToEndTest extends CommandBaseTest { + + /** The distinctor of the {@code /error} command under the default, {@code ENTITY_NAME_AND_ACTION_NAME}. */ + private static final String ERROR = "DUMMY|ERROR"; + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void aRetryAfterARecoverableFailureIsExecutedAgain() { + var key = UUID.randomUUID().toString(); + + var first = post(key); + var retry = post(key); + + assertTrue(first.getStatusCode().is4xxClientError(), "The command must fail, got " + first.getStatusCode()); + assertFalse(servedFromCache(retry), "A retry after a recoverable failure must be executed, not answered from the store."); + assertEquals(first.getStatusCode(), retry.getStatusCode(), "Executed again, it fails again the same way."); + } + + @Test + public void theFailureStaysOnRecordUnderTheMovedKey() { + var key = UUID.randomUUID().toString(); + + post(key); + + assertTrue(repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, ERROR).isEmpty(), + "The original key must be free for the retry."); + + var moved = repository.findAll().stream().filter(row -> row.getIdempotencyKey().startsWith(key + "_RE")).toList(); + + assertEquals(1, moved.size(), "The failed command must still be recorded, under its moved key."); + + CommandEntity row = moved.get(0); + + assertEquals(key + "_RE" + row.getId(), row.getIdempotencyKey()); + assertEquals(CommandState.ERROR, row.getState()); + assertEquals(ERROR, row.getCustomIdempotencyDistinctor()); + assertNotNull(row.getResponseStatusCode(), "The answer the client was sent must be recorded against the moved row."); + } + + private ResponseEntity post(String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy/error", HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content("boom").build(), headers), String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst("x-served-from-cache")); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } + + @Configuration + static class RecoverableDummyFailures { + + @Bean + RecoverableCommandErrorClassifier recoverableCommandErrorClassifier() { + return error -> error instanceof DummyException; + } + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java new file mode 100644 index 00000000000..986b893d5d6 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java @@ -0,0 +1,49 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.junit.jupiter.api.Test; + +class RecoverableErrorKeyTest { + + @Test + void aKeyThatFitsKeepsItsTextAndGainsTheRowId() { + assertThat(RecoverableErrorKey.movedKey("idk", 42)).isEqualTo("idk_RE42"); + } + + @Test + void aKeyThatWouldNotFitIsHashedSoThatTheMovedKeyAlwaysFits() { + var longKey = "k".repeat(RecoverableErrorKey.KEY_LENGTH); + var moved = RecoverableErrorKey.movedKey(longKey, Long.MAX_VALUE); + + assertThat(moved).hasSizeLessThanOrEqualTo(RecoverableErrorKey.KEY_LENGTH).endsWith("_RE" + Long.MAX_VALUE) + .matches("[0-9a-f]{" + RecoverableErrorKey.HASH_LENGTH + "}_RE[0-9]+"); + assertThat(RecoverableErrorKey.movedKey(longKey, Long.MAX_VALUE)).as("The same key must always move to the same place.") + .isEqualTo(moved); + } + + @Test + void theLongestKeyThatFitsIsNotHashed() { + var key = "k".repeat(RecoverableErrorKey.KEY_LENGTH - "_RE7".length()); + + assertThat(RecoverableErrorKey.movedKey(key, 7)).isEqualTo(key + "_RE7"); + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java new file mode 100644 index 00000000000..2647098d9da --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java @@ -0,0 +1,156 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import java.util.concurrent.CompletionException; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.web.context.request.RequestContextHolder; +import org.springframework.web.context.request.ServletRequestAttributes; + +class IdempotencyRecoverableErrorCommandHookTest { + + private static final String KEY = "idk"; + + private static final long COMMAND_ID = 42L; + + private final CommandStore store = mock(CommandStore.class); + + private final MockHttpServletRequest request = new MockHttpServletRequest(); + + @BeforeEach + void bindRequest() { + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, KEY); + RequestContextHolder.setRequestAttributes(new ServletRequestAttributes(request)); + } + + @AfterEach + void unbindRequest() { + RequestContextHolder.resetRequestAttributes(); + } + + @Test + void aRecoverableFailureReleasesTheKey() { + var ctx = failed(new IllegalStateException("try again")); + + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).as("The failure moves aside, so the audit hook stores it there.") + .isEqualTo("idk_RE42"); + assertThat(request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE)) + .as("The answer the client is sent has to be recorded against the moved row.").isEqualTo("idk_RE42"); + verify(store).existsByKey("idk_RE42", "LOAN|CREATE"); + } + + @Test + void anyOtherFailureKeepsTheKey() { + var ctx = failed(new IllegalStateException("no")); + + hook(error -> false).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + assertThat(request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE)).isEqualTo(KEY); + } + + @Test + void aRefusedRepeatReleasesNothing() { + var ctx = failed(new IllegalStateException("try again")); + + ctx.setSkipExecution(true); + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).as("A repeat never claimed the key, so it is not its to release.").isEqualTo(KEY); + verifyNoInteractions(store); + } + + @Test + void aMovedKeyThatIsAlreadyTakenKeepsTheFailureUnderTheOriginalKey() { + var ctx = failed(new IllegalStateException("try again")); + + when(store.existsByKey(anyString(), anyString())).thenReturn(true); + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + } + + @Test + void aClassifierThatFailsKeepsTheKeyAndLetsTheOriginalErrorThrough() { + var ctx = failed(new IllegalStateException("try again")); + + hook(error -> { + throw new IllegalArgumentException("the configuration could not be read"); + }).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + } + + @Test + void aFailureHandedBackWrappedIsClassifiedByWhatItWraps() { + var ctx = failed(new CompletionException(new UnsupportedOperationException("try again"))); + + hook(error -> error instanceof UnsupportedOperationException).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo("idk_RE42"); + } + + private IdempotencyRecoverableErrorCommandHook hook(RecoverableCommandErrorClassifier classifier) { + return new IdempotencyRecoverableErrorCommandHook(store, classifier); + } + + private static CommandContext failed(Throwable error) { + var command = new TestCommand(); + + command.setIdempotencyKey(KEY); + command.setCustomIdempotencyDistinctor("LOAN|CREATE"); + command.setCommandId(COMMAND_ID); + + var ctx = CommandContext.builder().command(command).build(); + + ctx.setError(error); + + return ctx; + } + + private static final class TestCommand extends Command { + + @Override + public String entityName() { + return "LOAN"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java b/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java new file mode 100644 index 00000000000..7eafbe62b7d --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java @@ -0,0 +1,39 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +/** + * Decides whether a command failed in a way that a retry under the same idempotency key should execute again, rather + * than be answered with the stored failure. + * + *

+ * A failed command normally owns its idempotency key for good: every repeat is answered with the same failure. That is + * right for a failure the request itself caused, and wrong for one a retry could get past - a lock that could not be + * taken, a dependency that was briefly unavailable, a business rule the client was told to wait out. For those the key + * is released, so that the retry the client was right to make is executed. + * + *

+ * The idempotency module falls back to treating nothing as recoverable. The application supplies the real rules, which + * in Fineract are the same ones the legacy command processing applies. + */ +@FunctionalInterface +public interface RecoverableCommandErrorClassifier { + + boolean isRecoverable(Throwable error); +} diff --git a/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java b/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java new file mode 100644 index 00000000000..2f2f8a3f678 --- /dev/null +++ b/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java @@ -0,0 +1,41 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.commands.service; + +import lombok.RequiredArgsConstructor; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.springframework.stereotype.Component; + +/** + * Gives the new command processing the same notion of a recoverable failure as the legacy one, so that a retry under + * the same idempotency key is executed again in exactly the cases where it is today: an exception marked + * {@code RecoverableError}, or one whose error codes are all listed in the {@code idempotency-recoverable-error-codes} + * global configuration. + */ +@Component +@RequiredArgsConstructor +public class RecoverableCommandErrorClassifierAdapter implements RecoverableCommandErrorClassifier { + + private final RecoverableErrorClassifier classifier; + + @Override + public boolean isRecoverable(Throwable error) { + return error instanceof RuntimeException runtimeException && classifier.isRecoverable(runtimeException); + } +} diff --git a/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java b/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java new file mode 100644 index 00000000000..17eacf71677 --- /dev/null +++ b/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java @@ -0,0 +1,52 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.commands.service; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import org.junit.jupiter.api.Test; + +class RecoverableCommandErrorClassifierAdapterTest { + + private final RecoverableErrorClassifier legacy = mock(RecoverableErrorClassifier.class); + + private final RecoverableCommandErrorClassifierAdapter adapter = new RecoverableCommandErrorClassifierAdapter(legacy); + + @Test + void theLegacyRulesDecide() { + var recoverable = new IllegalStateException("recoverable"); + var permanent = new IllegalStateException("permanent"); + + when(legacy.isRecoverable(recoverable)).thenReturn(true); + when(legacy.isRecoverable(permanent)).thenReturn(false); + + assertThat(adapter.isRecoverable(recoverable)).isTrue(); + assertThat(adapter.isRecoverable(permanent)).isFalse(); + } + + @Test + void aFailureTheLegacyRulesCannotClassifyIsNotRecoverable() { + assertThat(adapter.isRecoverable(new Exception("checked"))).isFalse(); + assertThat(adapter.isRecoverable(null)).isFalse(); + verifyNoInteractions(legacy); + } +} diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index c2e46e5d67f..28b1f028908 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -102,7 +102,8 @@ that never happened. | The original status code and body. | Failed -| The original status code and body, so a repeat of a failure fails exactly as the original did. +| The original status code and body, so a repeat of a failure fails exactly as the original did - unless the failure +was recoverable, in which case the repeat is executed again. See <>. | Still being processed, claimed within `claim-timeout` | `425 Too Early`. The original has not finished, so there is nothing to replay yet and the caller should retry. @@ -152,6 +153,22 @@ A repeat is also only replayed when it carries the same request as the original. with a different body is rejected with `409 Conflict` instead of being answered with the earlier result, which would otherwise report success for something that was never carried out. +=== Recoverable failures + +Some failures are worth retrying under the same key: a lock that could not be taken, a dependency that was briefly +unavailable. The new command processing treats them as the legacy one does. A failure is recoverable when its +exception is marked `RecoverableError`, or when all of its error codes are listed in the +`idempotency-recoverable-error-codes` global configuration. + +A command that failed recoverably gives its key up: its record is moved to `_RE`, where `` is the +record's own id, and a retry with the original key is executed as a new command. The failure stays on record under the +moved key, together with the answer the client was sent. A key too long to take the suffix is replaced by the first 40 +hex characters of its SHA-256 hash. If the moved key is somehow already taken, or anything else stops the move, the +failure stays under the original key, and a retry is answered with it as for any other failure. + +The rules come from the application through a `RecoverableCommandErrorClassifier` bean; Fineract provides one that +applies the legacy rules. Without one, no failure is recoverable. + === Requires auditing Claiming a key writes the command record, but the idempotency hooks never write it again: it is the audit hooks that From ab1ec1644ed4918e9b14e172a49937ed05292884 Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 17:58:24 +0000 Subject: [PATCH 11/11] FINERACT-2485: Allow the claim timeout to be switched off The legacy command processing answers a repeat of an unfinished command 425 Too Early for as long as it stays unfinished. The new command processing turns that into 409 after fineract.command.idempotency.claim-timeout, so that a claim abandoned by a dead process does not answer 425 for ever. The timeout stays on by default, at 10 minutes. Setting it to 0, or leaving it empty, now switches it off and restores the legacy answer, for deployments whose clients rely on it. A negative value is refused at startup: a negative age is always exceeded, so even a command that is still running would be declared abandoned. --- .../IdempotencyCommandProperties.java | 4 ++++ .../IdempotencyCommandPropertyCheck.java | 14 +++++++++++++ .../hook/IdempotencyCheckCommandHook.java | 12 ++++++++++- .../IdempotencyCommandPropertyCheckTest.java | 20 +++++++++++++++++++ .../hook/IdempotencyCheckCommandHookTest.java | 13 ++++++++++++ .../en/chapters/architecture/idempotency.adoc | 7 ++++++- .../src/main/resources/application.properties | 3 ++- 7 files changed, 70 insertions(+), 3 deletions(-) diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java index 6fec0c654dc..efb5e0230f5 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/IdempotencyCommandProperties.java @@ -69,6 +69,10 @@ public final class IdempotencyCommandProperties implements Serializable { * store gave up after its retries - would otherwise answer every repeat {@code 425 Too Early} for ever, and a * client following that advice retries for ever. Long enough that a slow command is not declared dead: the key is * never re-executed, but a repeat past this point is refused, and the caller has to use a new one. + * + *

+ * Zero or empty switches the timeout off: a repeat of an unfinished claim is then answered {@code 425 Too Early} + * for as long as it stays unfinished, as in the legacy command processing. A negative value is refused at startup. */ @Builder.Default private Duration claimTimeout = Duration.ofMinutes(10); diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java index 067fafdc09d..0c657f0f84c 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java @@ -75,6 +75,20 @@ void check() { requireHook(COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, audit.getHookPostEnabled(), "completed"); requireHook(COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, audit.getHookErrorEnabled(), "failed"); + var claimTimeout = idempotency.getClaimTimeout(); + + if (claimTimeout != null && claimTimeout.isNegative()) { + // a negative age is always exceeded, so every unfinished claim - including one still running - would be + // declared abandoned; zero is how the timeout is switched off + throw new IllegalStateException("fineract.command.idempotency.claim-timeout must not be negative, but is " + claimTimeout + + ". Use 0 to switch the timeout off."); + } + + if (claimTimeout == null || claimTimeout.isZero()) { + log.info("Command idempotency claim timeout is off: a repeat of an unfinished command is answered 425 Too Early for as " + + "long as it stays unfinished."); + } + log.info("Command idempotency is enabled."); } diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java index 418726133c1..d717e40f32a 100644 --- a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -160,11 +160,21 @@ private CommandReplay replayFor(String key, String distinctorValue) { * claiming the key and recording the outcome, or the store gave up writing it. Nothing distinguishes the two from * the row, so age stands in for it. Treated as abandoned only well past the point where a command could still be * working, because the cost of being wrong is telling a caller their request failed while it is still running. + * + *

+ * With no timeout configured - zero or empty - no claim is ever treated as abandoned, and a repeat of an unfinished + * one is answered {@code 425 Too Early} for as long as it stays unfinished, which is what the legacy command + * processing does. */ private boolean abandoned(CommandReplay replay) { var claimedAt = replay.claimedAt(); + var timeout = properties.getClaimTimeout(); + + if (timeout == null || timeout.isZero()) { + return false; + } - return claimedAt != null && claimedAt.isBefore(Instant.now().minus(properties.getClaimTimeout())); + return claimedAt != null && claimedAt.isBefore(Instant.now().minus(timeout)); } /** diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java index c45c444a579..70b1c38f032 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java @@ -88,6 +88,26 @@ void auditHooksOffWithoutIdempotencyStarts() { .run(context -> assertThat(context).as("Without idempotency nothing depends on the hooks.").hasNotFailed()); } + @Test + void aClaimTimeoutOfZeroSwitchesTheTimeoutOffAndStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=0").run(context -> assertThat(context) + .as("Zero is how the timeout is switched off, which is the legacy behaviour.").hasNotFailed()); + } + + @Test + void anEmptyClaimTimeoutSwitchesTheTimeoutOffAndStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=").run(context -> assertThat(context) + .as("An empty value, as an unset environment variable gives, is the same as zero.").hasNotFailed()); + } + + @Test + void aNegativeClaimTimeoutRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=-1m") + .run(context -> assertThat(context) + .as("A negative age is always exceeded, so even a running command would be declared abandoned.").hasFailed() + .getFailure().rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("claim-timeout")); + } + @Test void bothOffStarts() { contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.enabled=false").run( diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java index b3f15f0e7e8..15c06087a44 100644 --- a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -221,6 +221,19 @@ void aClaimThatIsStillWithinItsTimeIsToldToComeBack() { "A command that could still be running must not be declared dead."); } + @Test + void withTheTimeoutSwitchedOffAnUnfinishedClaimIsToldToComeBackHoweverOld() { + for (var timeout : new Duration[] { Duration.ZERO, null }) { + var legacy = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().claimTimeout(timeout).build(), + new NoCustomIdempotencyDistinctor()); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofDays(30)))); + + assertThrows(CommandIdempotencyInProgressException.class, () -> legacy.onBefore(context(KEY)), + "With no timeout (" + timeout + ") a claim is never declared abandoned, as in the legacy processing."); + } + } + private void duplicate(CommandReplay replay) { when(store.claim(any())).thenReturn(false); when(store.getReplayByKey(KEY, "")).thenReturn(replay); diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index 28b1f028908..739808a91bb 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -109,7 +109,8 @@ was recoverable, in which case the repeat is executed again. See <>. +| `409 Conflict`, saying the command never finished. With the timeout switched off, `425 Too Early` as above. See +<>. | Completed, but its stored result cannot be reconstructed | `409 Conflict`, saying so. The key has been used and its answer can no longer be produced - reporting a server error @@ -208,6 +209,10 @@ Past `fineract.command.idempotency.claim-timeout`, such a claim is treated as ab it: set the timeout comfortably above the slowest command rather than tightly, because the cost of being wrong is telling a caller their request failed while it is still running. +The timeout is on by default, at 10 minutes. Setting `claim-timeout` to `0` (or leaving it empty) switches it off: an +unfinished claim is then answered `425 Too Early` for as long as it stays unfinished, which is what the legacy command +processing does. A negative value is refused at startup. + IMPORTANT: The key is refused, not released. The command that claimed it may have reached the database before whatever stopped it, so running it again is exactly the duplicate this mechanism exists to prevent. Whether the original took effect has to be established some other way, and a retry needs a new idempotency key. diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index d3ded10e206..430aa2ea6fa 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -958,7 +958,8 @@ fineract.command.idempotency.hook-check-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_ # How long a claimed command may stay unfinished before a repeat of its key is refused rather than told to retry. # Guards against a claim that is never resolved - the process died before recording the outcome - which would # otherwise answer 425 for ever. The key is never re-executed, only refused, so set it comfortably above the -# slowest command rather than tightly. +# slowest command rather than tightly. 0 (or empty) switches the timeout off and answers 425 for as long as the claim +# stays unfinished, as the legacy command processing does. fineract.command.idempotency.claim-timeout=${FINERACT_COMMAND_IDEMPOTENCY_CLAIM_TIMEOUT:10m} # What an idempotency key is unique together with. ENTITY_NAME_AND_ACTION_NAME (default): the command's entity and # action names joined with "|" (for example LOAN|CREATE), so a key may be used once per entity and action, the way the