From fee7367c39bca549712fc6067cce1b878178f73c Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 18:48:07 +0000 Subject: [PATCH 1/5] FINERACT-2485: Pass a CommandContext to command hooks Command hooks now receive a CommandContext - the command, its response, its error and its state - instead of separate arguments, so a before hook can mark a command as handled (skipExecution) and have the dispatcher return a response it supplied, and can stop the remaining hooks (skipHooks). The synchronous, async and disruptor dispatchers all honour it; the disruptor dispatcher hands each command a fresh future before publishing its slot. Each command module gets constants for its properties, and the hook switches move under the module they belong to (fineract.command.audit.hook-*-enabled, fineract.command.hook-*-enabled). The audit module reports at startup which of its hooks are on. The JDBC store is renamed to its Jdbc*/Json* types and stores a CommandContext. The webhook command hooks are adapted to the new hook interface. Step 1 of 9 of FINERACT-2485. Co-authored-by: Aleksandar Vidakovic --- .../command/async/AsyncCommandConstants.java | 30 ++++ .../command/async/AsyncCommandProperties.java | 4 +- .../AsyncCommandDispatcher.java | 34 +++-- .../AsyncCommandAutoConfiguration.java | 7 +- .../async/AsyncCommandDispatcherTest.java | 86 ++++++++++++ .../command/audit/AuditCommandConstants.java | 16 ++- .../command/audit/AuditCommandProperties.java | 18 ++- .../check/AuditCommandPropertyCheck.java | 61 +++++++++ .../audit/hook/AuditCommandHookAfter.java | 16 ++- .../audit/hook/AuditCommandHookBefore.java | 27 +++- .../audit/hook/AuditCommandHookError.java | 29 ++-- .../AuditCommandAutoConfiguration.java | 7 +- ...CommandPropertyCheckAutoConfiguration.java | 32 +++++ ...ot.autoconfigure.AutoConfiguration.imports | 3 +- .../check/AuditCommandPropertyCheckTest.java | 103 ++++++++++++++ .../resources/application-test.properties | 6 +- .../disruptor/DisruptorCommandConstants.java | 30 ++++ .../disruptor/DisruptorCommandProperties.java | 4 +- .../DisruptorCommandDispatcher.java | 55 +++++--- .../DisruptorCommandAutoConfiguration.java | 7 +- .../CompleteableCommandEventHandlerTest.java | 104 ++++++++++++++ .../command/jdbc/JdbcCommandConstants.java | 30 ++++ .../command/jdbc/JdbcCommandProperties.java | 4 +- .../starter/JdbcCommandAutoConfiguration.java | 7 +- .../command/jdbc/store/JdbcCommandStore.java | 69 ++-------- ...sitory.java => JdbcCommandRepository.java} | 4 +- ...mandMapper.java => JdbcCommandMapper.java} | 4 +- ...JsonMapper.java => JsonCommandMapper.java} | 2 +- ...st.java => JdbcCommandRepositoryTest.java} | 10 +- .../command/core/CommandConstants.java | 9 ++ .../fineract/command/core/CommandContext.java | 80 +++++++++++ .../command/core/CommandDispatcher.java | 4 + .../command/core/CommandHookAfter.java | 2 +- .../command/core/CommandHookBefore.java | 4 +- .../command/core/CommandHookError.java | 4 +- .../command/core/CommandHookManager.java | 14 +- .../command/core/CommandProperties.java | 18 ++- .../fineract/command/core/CommandStore.java | 14 +- .../hook/ServletHeadersCommandHook.java | 30 ++-- .../command/hook/TimestampCommandHook.java | 11 +- .../command/hook/UsernameCommandHook.java | 11 +- .../DefaultCommandHookManager.java | 33 ++++- .../SynchronousCommandDispatcher.java | 23 +++- .../command/starter/CommandConfiguration.java | 10 +- .../command/util/ServletHeaderUtil.java | 70 ++++++++++ .../DefaultCommandHookManagerTest.java | 127 +++++++++++++++++ .../SynchronousCommandDispatcherTest.java | 128 ++++++++++++++++++ .../resources/application-test.properties | 6 +- .../command/WebhookCommandHookAfter.java | 9 +- .../command/WebhookCommandHookError.java | 14 +- .../command/WebhookCommandHookAfterTest.java | 16 ++- .../command/WebhookCommandHookErrorTest.java | 28 +++- .../service/TemplateDomainServiceImpl.java | 3 - .../src/main/resources/application.properties | 14 +- .../TemplateDomainServiceImplTest.java | 4 - .../resources/application-test.properties | 12 +- 56 files changed, 1271 insertions(+), 236 deletions(-) create mode 100644 fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java create mode 100644 fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.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-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java create mode 100644 fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java create mode 100644 fineract-command-disruptor/src/test/java/org/apache/fineract/command/disruptor/CompleteableCommandEventHandlerTest.java 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%) 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 create mode 100644 fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java create mode 100644 fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java 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 000000000000..8fd93a922a65 --- /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 832318ed96df..d1d5d7b348d2 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 7999af97c5b4..ffc9c1f90371 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,15 +19,20 @@ 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.CompletionException; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeoutException; 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 +43,47 @@ @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); + // whenComplete sees the failure wrapped; the hooks get the exception the handler threw, as they do + // from the synchronous dispatcher + ctx.setError(t instanceof CompletionException && t.getCause() != null ? t.getCause() : 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 d4410fb07fca..2f112586b5be 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-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java b/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java new file mode 100644 index 000000000000..a8caf6d4e0f1 --- /dev/null +++ b/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java @@ -0,0 +1,86 @@ +/** + * 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.junit.jupiter.api.Assertions.assertEquals; +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 java.util.List; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.atomic.AtomicInteger; +import org.apache.fineract.command.async.implementation.AsyncCommandDispatcher; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandHandlerManager; +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.implementation.DefaultCommandHookManager; +import org.junit.jupiter.api.Test; + +/** + * How the async dispatcher honours what the before hooks ask of it, and what it hands the error hooks. + */ +@SuppressWarnings({ "rawtypes", "unchecked" }) +class AsyncCommandDispatcherTest { + + private final List calls = new CopyOnWriteArrayList<>(); + private final AtomicInteger handled = new AtomicInteger(); + private final IllegalStateException failure = new IllegalStateException("handler failed"); + + private final CommandHandlerManager handler = new CommandHandlerManager() { + + @Override + public S handle(Command command) { + handled.incrementAndGet(); + throw failure; + } + }; + + @Test + void skipExecutionReturnsTheHookResponseWithoutRunningTheHandlerOrTheAfterHooks() { + CommandHookBefore answering = ctx -> { + ctx.setResponse("replayed"); + ctx.setSkipExecution(true); + }; + var dispatcher = dispatcher(List.of(answering), List.of(ctx -> calls.add("after")), List.of()); + + Object result = dispatcher.dispatch(new Command<>()).get(); + + assertEquals("replayed", result); + assertEquals(0, handled.get()); + assertTrue(calls.isEmpty(), "The after hooks must not run: " + calls); + } + + @Test + void errorHooksGetTheExceptionTheHandlerThrewNotTheCompletionWrapper() { + List errors = new CopyOnWriteArrayList<>(); + var dispatcher = dispatcher(List.of(), List.of(), List.of(ctx -> errors.add(ctx.getError()))); + + assertThrows(RuntimeException.class, () -> dispatcher.dispatch(new Command<>()).get()); + + assertEquals(1, errors.size()); + assertSame(failure, errors.get(0)); + } + + private AsyncCommandDispatcher dispatcher(List before, List after, List error) { + return new AsyncCommandDispatcher(handler, new DefaultCommandHookManager(before, after, error), new AsyncCommandProperties()); + } +} 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 5ba7b115822c..98fb754aa350 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,21 @@ */ 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_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 129957800980..75a46145a233 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,24 @@ @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; + /** + * 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 + private Boolean hookPreEnabled = true; + @Builder.Default + private Boolean hookPostEnabled = true; @Builder.Default - private Boolean enabled = false; + 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 000000000000..38af9182f4c9 --- /dev/null +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheck.java @@ -0,0 +1,61 @@ +/** + * 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 jakarta.annotation.PostConstruct; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +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 static final String RECOMMENDATION = "IT IS RECOMMENDED TO ENABLE THIS FEATURE IN PRODUCTION ENVIRONMENTS!"; + + private final AuditCommandProperties properties; + + @PostConstruct + 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; + } + + 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 {} 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 529ed0349618..d871b7829d5c 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 = true) 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 524f47537e0e..d81ba7692019 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,32 @@ @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", matchIfMissing = true) +final class AuditCommandHookBefore implements CommandHookBefore { private final CommandStore store; @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + if (ctx.isSkipExecution()) { + // an earlier hook has answered the command itself, so it is not executed and 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 audit for a command that will not be executed"); + return; + } + 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 fe1d2b6376a5..dff61cf35204 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,32 @@ @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", matchIfMissing = true) +final class AuditCommandHookError implements CommandHookError { private final CommandStore store; @Override - public void onError(Command command, Throwable error) { + 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(); - 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 7b186c6c4a5f..c11c5c49fdc7 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", 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 new file mode 100644 index 000000000000..82b3435b7dc0 --- /dev/null +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandPropertyCheckAutoConfiguration.java @@ -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. + */ +package org.apache.fineract.command.audit.starter; + +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 +@EnableConfigurationProperties(AuditCommandProperties.class) +@ComponentScan(COMMAND_AUDIT_CHECK_BASE_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 56b407045f37..6041b23e1fe2 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/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 000000000000..ece385ac7dd7 --- /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-audit/src/test/resources/application-test.properties b/fineract-command-audit/src/test/resources/application-test.properties index e160de083a82..5611a2cb03bc 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 000000000000..f478fcc93f8e --- /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 130990a85645..aeda9dca4448 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 59f48211ad07..971251d4a112 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,9 +56,7 @@ public class DisruptorCommandDispatcher implements CommandDispatcher, Closeable public Supplier dispatch(Command command) { requireNonNull(command, "Command must not be null"); - CommandEvent processedEvent = next(command); - - var future = processedEvent.getFuture(); + var future = next(CommandContext.builder().command(command).build()); return future::join; } @@ -70,25 +71,36 @@ 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(Command command) { + private CompletableFuture next(CommandContext ctx) { var ringBuffer = disruptor.getRingBuffer(); var sequenceId = ringBuffer.next(); - CommandEvent event = ringBuffer.get(sequenceId); - event.setCommand(command); - 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 @Setter public static class CommandEvent { - private Command command; - private CompletableFuture future = new CompletableFuture<>(); + private CommandContext context; + private CompletableFuture future; } @RequiredArgsConstructor @@ -100,18 +112,27 @@ public static class CompleteableCommandEventHandler implements EventHandler calls = new ArrayList<>(); + private final AtomicInteger handled = new AtomicInteger(); + + private final CommandHandlerManager handler = new CommandHandlerManager() { + + @Override + public S handle(Command command) { + handled.incrementAndGet(); + return (S) "handled"; + } + }; + + @Test + void skipExecutionCompletesWithTheHookResponseWithoutRunningTheHandlerOrTheAfterHooks() throws Exception { + CommandHookBefore answering = ctx -> { + ctx.setResponse("replayed"); + ctx.setSkipExecution(true); + }; + var event = event(); + + eventHandler(List.of(answering), List.of(ctx -> calls.add("after")), List.of()).onEvent(event, 0L, true); + + assertEquals("replayed", event.getFuture().get()); + assertEquals(0, handled.get()); + assertTrue(calls.isEmpty(), "The after hooks must not run: " + calls); + } + + @Test + void aFailingBeforeHookCompletesTheFutureExceptionallyAfterTheErrorHooks() { + var refused = new IllegalStateException("refused"); + CommandHookBefore refusing = ctx -> { + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + throw refused; + }; + var event = event(); + + eventHandler(List.of(refusing), List.of(), List.of(ctx -> calls.add("error"))).onEvent(event, 0L, true); + + var thrown = assertThrows(ExecutionException.class, () -> event.getFuture().get()); + assertSame(refused, thrown.getCause()); + assertEquals(List.of("error"), calls); + assertEquals(0, handled.get()); + } + + private static CommandEvent event() { + var event = new CommandEvent(); + event.setContext(CommandContext.builder().command(new Command<>()).build()); + event.setFuture(new CompletableFuture<>()); + return event; + } + + private CompleteableCommandEventHandler eventHandler(List before, List after, + List error) { + return new CompleteableCommandEventHandler(new DefaultCommandHookManager(before, after, error), handler); + } +} 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 000000000000..4f5d110ced73 --- /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 d7e0e2ebacef..8ad38a104ca4 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 c7603d549401..813ed6a82474 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 c943b0578e60..f1869ce875f4 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 @@ -20,8 +20,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; @@ -29,16 +27,14 @@ 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.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,53 +47,20 @@ @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); - } - - @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); - } - - @Override - public org.apache.fineract.command.core.CommandState getStateById(Long id) { - return repository.findById(id).map(CommandEntity::getState).orElse(UNKNOWN); - } - - @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); - } - - @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); - } - - @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 +82,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())) { @@ -137,11 +103,6 @@ void onStartup() { } } - @SneakyThrows - private Class forName(String clazz) { - return Class.forName(clazz); - } - private void write(Command command) throws IOException { var file = Path .of(properties.getFileDeadLetterQueuePath(), 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 7e5e34ea9adb..dcec7c4816ac 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 b83867335efa..9a4fe19e585e 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 dfcd21038360..faaa5369de8f 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/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 df2b2e802856..d8440147e96e 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 35f9c1db86ff..d56cb188dfdd 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 000000000000..dff6af7d1ebd --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java @@ -0,0 +1,80 @@ +/** + * 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; + +/** + * What the dispatcher and the hooks share while one command is processed. + * + *

+ * {@code command}, {@code response}, {@code error} and {@code state} are data: the dispatcher fills them in as the + * command progresses and hooks read them (a hook may also replace the response it returns). {@code skipExecution} and + * {@code skipHooks} go the other way: they are instructions a hook gives, and the dispatcher and the hook manager act + * on them. + * + *

+ * A context belongs to a single dispatch of a single command and is not reused. + */ +@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; + + /** + * Set by a before hook that has answered the command itself, e.g. by replaying a stored result. The dispatcher then + * does not run the handler and returns {@code response} as it is. The after hooks are not run either: nothing was + * executed, so there is nothing to audit or announce. The dispatcher does not touch {@code state} on this path; the + * hook that skips execution is responsible for whatever it leaves there. + * + *

+ * Hooks that record an execution (auditing, webhooks) check this flag, because a before hook that skips execution + * may still throw, and the error hooks then run for a command that was never executed. + */ + private boolean skipExecution; + + /** + * Set by a hook to stop the remaining hooks of the current phase (before, after or error) from running. It applies + * to that phase only: the hook manager clears it when the phase ends, also when a hook throws, so it never carries + * over into the next phase. + */ + private boolean skipHooks; +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandDispatcher.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandDispatcher.java index 52d504ade219..7f0bd3b46588 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandDispatcher.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandDispatcher.java @@ -22,5 +22,9 @@ public interface CommandDispatcher { + /** + * @return a supplier of the command's result. Call it once: whether the command runs when it is dispatched or when + * the supplier is called is up to the dispatcher, so calling it again may run the command again. + */ Supplier dispatch(Command command); } 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 ce479ab7f668..d252ce06cbac 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 7f5af0c6dc9f..22d1ad09f4f1 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 2730dd687293..9eb4c7a026c1 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 ca9f2d5e54cc..ce56a25762d3 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,19 @@ */ package org.apache.fineract.command.core; +/** + * Runs the hooks of one phase - before, after or error - in their order. + * + *

+ * A hook that throws is not isolated: the exception ends the phase and propagates to the dispatcher, which treats it + * like a failure of the command. A hook can stop the remaining hooks of a phase with {@code skipHooks} on the + * {@link CommandContext}; that request is cleared when the phase ends. + */ 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 6450cb589010..2a445bcfcf4d 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 @@ -48,4 +50,18 @@ public final class CommandProperties implements Serializable { @Builder.Default private String idemPotencyKeyHeaderName = "Idempotency-Key"; + + /** + * The core hooks are on unless switched off. 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 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 a93135c9e8e6..da1106b19dee 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,5 @@ public interface CommandStore { - T getRequestById(Long id); - - T getResponseById(Long id); - - CommandState getStateById(Long id); - - T getRequestByKey(String key); - - 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 b2bbeb3906b1..e353f904d9eb 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,30 +20,32 @@ 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 { +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED, havingValue = "true", matchIfMissing = true) +final class ServletHeadersCommandHook implements CommandHookBefore { private final CommandProperties properties; @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)); } @@ -51,20 +53,4 @@ public void onBefore(Command command) { 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 5ddbf41abc1c..a1cfec6b4f84 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", matchIfMissing = 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 d3d0d74a43b3..e3da6b3f92ad 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", matchIfMissing = 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 535af2dc8c84..d319d01fa347 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 @@ -19,9 +19,10 @@ package org.apache.fineract.command.implementation; import java.util.List; +import java.util.function.BiConsumer; 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 +42,35 @@ 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) { + run("pre", beforeHooks, ctx, CommandHookBefore::onBefore); } @Override - public void after(Command command, Object response) { - afterHooks.forEach(processor -> processor.onAfter(command, response)); + public void after(CommandContext ctx) { + run("post", afterHooks, ctx, CommandHookAfter::onAfter); } @Override - public void error(Command command, Throwable error) { - errorHooks.forEach(processor -> processor.onError(command, error)); + public void error(CommandContext ctx) { + run("error", errorHooks, ctx, CommandHookError::onError); + } + + private void run(String phase, List hooks, CommandContext ctx, BiConsumer invoke) { + try { + for (var hook : hooks) { + invoke.accept(hook, ctx); + + if (ctx.isSkipHooks()) { + log.debug("Skipping remaining {} hooks after: {}", phase, hook.getClass().getCanonicalName()); + + return; + } + } + } finally { + // skipHooks stops the rest of this phase only. It is cleared here, also when a hook throws, so that it + // never carries over: a before hook that sets it and then throws must not silence the error hooks + ctx.setSkipHooks(false); + } } } 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 227210e3381a..36417e2f35ba 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; @@ -44,16 +46,29 @@ public Supplier dispatch(final Command command) { requireNonNull(command, "Command must not be null"); return () -> { + // a fresh context for every call, so that the supplier can be called again without seeing what the + // previous call left in it + final var ctx = CommandContext.builder().command(command).build(); + 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 c5048b75c288..c83726eaa052 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 000000000000..9aceba02850e --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java @@ -0,0 +1,70 @@ +/** + * 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() {} + + /** + * 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(); + + 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; + } + + /** + * 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/DefaultCommandHookManagerTest.java b/fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java new file mode 100644 index 000000000000..634dab169f3b --- /dev/null +++ b/fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java @@ -0,0 +1,127 @@ +/** + * 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.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.util.ArrayList; +import java.util.List; +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; +import org.apache.fineract.command.implementation.DefaultCommandHookManager; +import org.junit.jupiter.api.Test; + +/** + * {@code skipHooks} is how a hook stops the rest of its phase. It must stop exactly that phase and nothing else: it is + * cleared when the phase ends, also when a hook throws, so that the next phase starts with every hook in it. + */ +@SuppressWarnings({ "rawtypes", "unchecked" }) +class DefaultCommandHookManagerTest { + + private final List calls = new ArrayList<>(); + + @Test + void runsEveryHookOfAPhaseInOrder() { + var manager = manager(List.of(before("b1"), before("b2")), List.of(after("a1"), after("a2")), List.of(error("e1"), error("e2"))); + var ctx = context(); + + manager.before(ctx); + manager.after(ctx); + manager.error(ctx); + + assertEquals(List.of("b1", "b2", "a1", "a2", "e1", "e2"), calls); + } + + @Test + void skipHooksStopsTheRestOfThePhaseAndIsClearedAfterwards() { + CommandHookBefore skipping = ctx -> { + calls.add("b1"); + ctx.setSkipHooks(true); + }; + var manager = manager(List.of(skipping, before("b2")), List.of(after("a1")), List.of()); + var ctx = context(); + + manager.before(ctx); + + assertEquals(List.of("b1"), calls, "The hook after the one that set skipHooks must not run."); + assertFalse(ctx.isSkipHooks(), "skipHooks applies to one phase only."); + + manager.after(ctx); + + assertEquals(List.of("b1", "a1"), calls, "The next phase runs in full."); + } + + @Test + void skipHooksIsClearedWhenTheHookThatSetItThrows() { + CommandHookBefore skippingThenFailing = ctx -> { + ctx.setSkipHooks(true); + throw new IllegalStateException("refused"); + }; + var manager = manager(List.of(skippingThenFailing), List.of(), List.of(error("e1"), error("e2"))); + var ctx = context(); + + assertThrows(IllegalStateException.class, () -> manager.before(ctx)); + assertFalse(ctx.isSkipHooks(), "A before hook that throws must not leave the error phase silenced."); + + manager.error(ctx); + + assertEquals(List.of("e1", "e2"), calls); + } + + @Test + void skipHooksStopsTheErrorPhaseLikeAnyOther() { + CommandHookError skipping = ctx -> { + calls.add("e1"); + ctx.setSkipHooks(true); + }; + var manager = manager(List.of(), List.of(), List.of(skipping, error("e2"))); + var ctx = context(); + + manager.error(ctx); + + assertEquals(List.of("e1"), calls); + assertFalse(ctx.isSkipHooks()); + } + + private static DefaultCommandHookManager manager(List before, List after, + List error) { + return new DefaultCommandHookManager(before, after, error); + } + + private static CommandContext context() { + return CommandContext.builder().command(new Command<>()).build(); + } + + private CommandHookBefore before(String name) { + return ctx -> calls.add(name); + } + + private CommandHookAfter after(String name) { + return ctx -> calls.add(name); + } + + private CommandHookError error(String name) { + return ctx -> calls.add(name); + } +} diff --git a/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java b/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java new file mode 100644 index 000000000000..54629afe06d6 --- /dev/null +++ b/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java @@ -0,0 +1,128 @@ +/** + * 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.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +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 java.util.ArrayList; +import java.util.List; +import java.util.concurrent.atomic.AtomicInteger; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandHandlerManager; +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.CommandState; +import org.apache.fineract.command.implementation.DefaultCommandHookManager; +import org.apache.fineract.command.implementation.SynchronousCommandDispatcher; +import org.junit.jupiter.api.Test; + +/** + * How the synchronous dispatcher honours what the before hooks ask of it. + */ +@SuppressWarnings({ "rawtypes", "unchecked" }) +class SynchronousCommandDispatcherTest { + + private final List calls = new ArrayList<>(); + private final AtomicInteger handled = new AtomicInteger(); + + private final CommandHandlerManager handler = new CommandHandlerManager() { + + @Override + public S handle(Command command) { + handled.incrementAndGet(); + return (S) "handled"; + } + }; + + @Test + void skipExecutionReturnsTheHookResponseWithoutRunningTheHandlerOrTheAfterHooks() { + CommandHookBefore answering = ctx -> { + ctx.setResponse("replayed"); + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + }; + var dispatcher = dispatcher(List.of(answering, ctx -> calls.add("before")), List.of(ctx -> calls.add("after")), List.of()); + + Object result = dispatcher.dispatch(new Command<>()).get(); + + assertEquals("replayed", result); + assertEquals(0, handled.get(), "A command whose execution is skipped must not reach its handler."); + assertTrue(calls.isEmpty(), "Neither the remaining before hooks nor the after hooks run: " + calls); + } + + @Test + void skipExecutionWithoutSkipHooksStillRunsTheRemainingBeforeHooks() { + CommandHookBefore answering = ctx -> { + ctx.setResponse("replayed"); + ctx.setSkipExecution(true); + }; + var dispatcher = dispatcher(List.of(answering, ctx -> calls.add("before")), List.of(ctx -> calls.add("after")), List.of()); + + Object result = dispatcher.dispatch(new Command<>()).get(); + + assertEquals("replayed", result); + assertEquals(0, handled.get()); + assertEquals(List.of("before"), calls); + } + + @Test + void errorHooksRunAfterABeforeHookThatSkippedAndThrew() { + var refused = new IllegalStateException("refused"); + CommandHookBefore refusing = ctx -> { + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + throw refused; + }; + List errors = new ArrayList<>(); + var dispatcher = dispatcher(List.of(refusing), List.of(), List.of(ctx -> errors.add(ctx.getError()), ctx -> calls.add("error2"))); + + var thrown = assertThrows(IllegalStateException.class, () -> dispatcher.dispatch(new Command<>()).get()); + + assertSame(refused, thrown); + assertEquals(List.of(refused), errors, "The error hooks see the exception the hook threw."); + assertEquals(List.of("error2"), calls, "skipHooks set in the before phase must not silence the error phase."); + } + + @Test + void everyCallOfTheSupplierStartsFromAFreshContext() { + List seen = new ArrayList<>(); + CommandHookBefore recording = ctx -> { + seen.add(ctx.getState()); + seen.add(ctx.getResponse()); + }; + var dispatcher = dispatcher(List.of(recording), List.of(), List.of()); + var supplier = dispatcher.dispatch(new Command<>()); + + supplier.get(); + supplier.get(); + + assertEquals(CommandState.UNDER_PROCESSING, seen.get(2), "The second call must not see the first call's state."); + assertNull(seen.get(3), "The second call must not see the first call's response."); + } + + private SynchronousCommandDispatcher dispatcher(List before, List after, + List error) { + return new SynchronousCommandDispatcher(handler, new DefaultCommandHookManager(before, after, error)); + } +} diff --git a/fineract-command/src/test/resources/application-test.properties b/fineract-command/src/test/resources/application-test.properties index 6b548107d110..182badf97be7 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-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 4cd4e71aa9d7..31da6d756db4 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 ba4d9b71dbb3..c187cd4fa893 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,19 +31,23 @@ */ @RequiredArgsConstructor @Component -final class WebhookCommandHookError implements CommandHookError { +final class WebhookCommandHookError implements CommandHookError { private final WebhookCommandEventPublisher publisher; @Override - public void onError(Command command, Throwable error) { - if (!(command instanceof HookableCommand hookable)) { + public void onError(CommandContext ctx) { + var command = ctx.getCommand(); + + // a command whose execution was skipped never ran, so it did not fail: the error is about the request (e.g. a + // refused repeat of an idempotency key), not about a change to announce + if (ctx.isSkipExecution() || !(command instanceof HookableCommand hookable)) { 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(), 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 1415941da4aa..55fe6aa322a5 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 af68e2a6f08b..09fd50da3cff 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,17 @@ 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); + } + + @Test + void shouldIgnoreCommandWhoseExecutionWasSkipped() { + final CommandContext ctx = errorContext(hookableCommand(), new IllegalStateException("refused repeat")); + ctx.setSkipExecution(true); + + underTest.onError(ctx); verifyNoInteractions(eventPublisher, errorHandler); } @@ -158,14 +169,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 +207,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(); + } } 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 520245966c2a..10f774d35ea3 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 5367286a4644..cbf1f1181cad 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -899,12 +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} +# the hook switches were read from the variables without the _ENABLED suffix up to 1.16.x; those are still honoured +# when the new one is not set, so an upgraded deployment keeps the hooks it switched off +fineract.command.audit.hook-pre-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE_ENABLED:${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE:true}} +fineract.command.audit.hook-post-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED:${FINERACT_COMMAND_PROCESSORS_AUDIT_POST:true}} +fineract.command.audit.hook-error-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR_ENABLED:${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR:true}} +fineract.command.hook-servlet-headers-enabled=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADERS_ENABLED:${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_PRE:true}} +fineract.command.hook-timestamp-enabled=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_ENABLED:${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_PRE:true}} +fineract.command.hook-username-enabled=${FINERACT_COMMAND_PROCESSORS_USERNAME_ENABLED:${FINERACT_COMMAND_PROCESSORS_USERNAME_PRE: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} 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 beae8b6aced7..92c1020452ef 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 929985f8259e..b9851c21e1dd 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 From 950fac61cd2c377236c44bd3854a7ccc8e78c7cb Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 18:48:08 +0000 Subject: [PATCH 2/5] FINERACT-2485: Make the Jackson 3 mapper agree with the Jersey wire format The command store runs on Jackson 3 while Jersey can only run on Jackson 2 (jersey-media-json-jackson 4.0.2 has no Jackson 3 support). Jackson3ObjectMapperConfig defines the application's Jackson 3 mapper to produce the same JSON as the web mapper: the same date, time, ExternalId and Month formats, NON_NULL inclusion, and the two date-time defaults Jackson 3 turned off (WRITE_DATES_AS_TIMESTAMPS, WRITE_DURATIONS_AS_TIMESTAMPS). java.time.Month is written by name, because Jackson 3 writes it as a number that a Jackson 2 client reads back as the wrong month. Credential masking is reapplied: the Jackson 2 MaskedValueSerializer annotation is invisible to Jackson 3. JacksonWireFormatEquivalenceTest pins the agreement, and Jackson3ObjectMapperWiringTest checks that this mapper, not Spring Boot's default, is the one injected. Step 2 of 9 of FINERACT-2485. --- .../jackson3/Jackson3ObjectMapperConfig.java | 67 ++++ .../jackson3/Jackson3WebFormatModule.java | 332 ++++++++++++++++++ .../Jackson3ObjectMapperWiringTest.java | 64 ++++ .../JacksonWireFormatEquivalenceTest.java | 267 ++++++++++++++ ...JacksonWireFormatCharacterizationTest.java | 209 +++++++++++ 5 files changed, 939 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/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 000000000000..881746648a39 --- /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 000000000000..d97ee6b45daf --- /dev/null +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3WebFormatModule.java @@ -0,0 +1,332 @@ +/** + * 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.Arrays; +import java.util.Date; +import java.util.List; +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 { + + private static final Month[] MONTHS = Month.values(); + + @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. Nothing + // outside that range is a month, and it is refused as bad input, as Jackson 2 refuses it + int ordinal = parser.getIntValue(); + if (ordinal < 0 || ordinal >= MONTHS.length) { + return (Month) context.handleWeirdNumberValue(Month.class, ordinal, + "not one of the values accepted for Enum class: ordinal must be between 0 and %d", MONTHS.length - 1); + } + return MONTHS[ordinal]; + } + var text = parser.getString(); + if (text != null) { + for (Month month : MONTHS) { + if (month.name().equalsIgnoreCase(text)) { + return month; + } + } + } + return (Month) context.handleWeirdStringValue(Month.class, text, "not one of the values accepted for Enum class: %s", + Arrays.toString(MONTHS)); + } + + @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. + * + *

+ * Masking is the one case reinstated here, but it is not the only one of its kind: every Jackson 2 databind + * annotation - {@code @JsonSerialize(using = ...)}, {@code @JsonDeserialize}, and the like - is invisible to + * Jackson 3. None is reachable from a command's request or response today. One that becomes reachable makes the + * command table hold different JSON than the API sends, and has to be mirrored here; + * {@code JacksonWireFormatEquivalenceTest} only notices it if its sample carries the annotated type. + */ + 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/Jackson3ObjectMapperWiringTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperWiringTest.java new file mode 100644 index 000000000000..a03e9b0be593 --- /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 000000000000..d52f46c349d4 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/JacksonWireFormatEquivalenceTest.java @@ -0,0 +1,267 @@ +/** + * 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 static org.junit.jupiter.api.Assertions.assertThrows; + +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.exc.InvalidFormatException; +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."); + } + + @Test + void aMonthGivenAsANumberIsReadAsTheSameOrdinalByBoth() throws Exception { + String request = "{\"month\":9}"; + + assertEquals(api.readValue(request, MonthOnly.class), commandStore.readValue(request, MonthOnly.class), + "Jackson 2 reads a number as the enum's zero-based ordinal; the command store must read it the same way."); + } + + @Test + void aMonthOutOfRangeIsRefusedAsBadInputByBoth() { + String request = "{\"month\":12}"; + + assertThrows(com.fasterxml.jackson.databind.exc.InvalidFormatException.class, () -> api.readValue(request, MonthOnly.class)); + assertThrows(InvalidFormatException.class, () -> commandStore.readValue(request, MonthOnly.class), + "A number that is not a month is bad input, not an index out of bounds."); + } + + @Test + void aMonthNameThatIsNotAMonthIsRefusedAsBadInputByBoth() { + String request = "{\"month\":\"SMARCH\"}"; + + assertThrows(com.fasterxml.jackson.databind.exc.InvalidFormatException.class, () -> api.readValue(request, MonthOnly.class)); + assertThrows(InvalidFormatException.class, () -> commandStore.readValue(request, MonthOnly.class)); + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class MonthOnly { + + private Month month; + } + + 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 000000000000..08d812c4a49b --- /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 13fd04e48c895b7337eeb4e1eaf1b531cbe1712f Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 18:48:08 +0000 Subject: [PATCH 3/5] FINERACT-2485: Retry every command handler UpdateWorkingDaysCommandHandler was the only command handler executing without a retry, so it gave up on the first contention where every other command tries again. It gets its own commandWorkingDaysUpdate instance, configured like the others. The product mix and floating rate handlers named retry instances that were never configured, so they fell back to resilience4j's defaults and retried on every exception. Their instances are configured like the others, and the unused commandMixTaxonomyMappingUpdate instance, left behind when the mix module was removed, is dropped. CommandHandlerRetryCoverageTest walks every CommandHandler on the classpath and fails if one is added without a retry, or names a retry instance that is not configured. Step 3 of 9 of FINERACT-2485. --- .../fineract/command/core/CommandHandler.java | 10 ++ .../UpdateWorkingDaysCommandHandler.java | 6 + .../src/main/resources/application.properties | 45 +++++- .../CommandHandlerRetryCoverageTest.java | 133 ++++++++++++++++++ 4 files changed, 187 insertions(+), 7 deletions(-) create mode 100644 fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHandler.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHandler.java index 4bd98b14c84c..01ecaa49c857 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHandler.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHandler.java @@ -25,6 +25,16 @@ public interface CommandHandler { RES handle(Command command); + /** + * The fallback a handler's {@code @Retry(fallbackMethod = "fallback")} names. + * + *

+ * Every handler that names it has to redeclare it with its own response type, even when the override does nothing + * but call this one. resilience4j only takes a fallback whose return type fits the return type of the method it + * guards, and this default returns {@code RES}, which erases to {@code Object}; a {@code handle} method returning a + * concrete response does not accept that. Without the override the fallback is not found: resilience4j logs "No + * fallback method match found" on every call and runs without one. + */ @SneakyThrows default RES fallback(Command command, Throwable t) { // NOTE: any command handler can override this default to implement more specialized fallbacks. 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 2528d818f8ee..71db6ca9fd35 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 cbf1f1181cad..f2a7d9f01fa1 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -615,6 +615,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 @@ -714,13 +719,39 @@ resilience4j.retry.instances.commandPaymentTypeDelete.enable-exponential-backoff resilience4j.retry.instances.commandPaymentTypeDelete.exponential-backoff-multiplier=${FINERACT_COMMAND_PAYMENT_TYPE_DELETE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} resilience4j.retry.instances.commandPaymentTypeDelete.retryExceptions=${FINERACT_COMMAND_PAYMENT_TYPE_DELETE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} -# mix taxonomy - -resilience4j.retry.instances.commandMixTaxonomyMappingUpdate.max-attempts=${FINERACT_COMMAND_MIX_TAXONOMY_MAPPING_UPDATE_RETRY_MAX_ATTEMPTS:3} -resilience4j.retry.instances.commandMixTaxonomyMappingUpdate.wait-duration=${FINERACT_COMMAND_MIX_TAXONOMY_MAPPING_UPDATE_RETRY_WAIT_DURATION:1s} -resilience4j.retry.instances.commandMixTaxonomyMappingUpdate.enable-exponential-backoff=${FINERACT_COMMAND_MIX_TAXONOMY_MAPPING_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} -resilience4j.retry.instances.commandMixTaxonomyMappingUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_MIX_TAXONOMY_MAPPING_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} -resilience4j.retry.instances.commandMixTaxonomyMappingUpdate.retryExceptions=${FINERACT_COMMAND_MIX_TAXONOMY_MAPPING_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} +# product mix + +resilience4j.retry.instances.commandProductMixCreate.max-attempts=${FINERACT_COMMAND_PRODUCT_MIX_CREATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandProductMixCreate.wait-duration=${FINERACT_COMMAND_PRODUCT_MIX_CREATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandProductMixCreate.enable-exponential-backoff=${FINERACT_COMMAND_PRODUCT_MIX_CREATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandProductMixCreate.exponential-backoff-multiplier=${FINERACT_COMMAND_PRODUCT_MIX_CREATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandProductMixCreate.retryExceptions=${FINERACT_COMMAND_PRODUCT_MIX_CREATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} + +resilience4j.retry.instances.commandProductMixUpdate.max-attempts=${FINERACT_COMMAND_PRODUCT_MIX_UPDATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandProductMixUpdate.wait-duration=${FINERACT_COMMAND_PRODUCT_MIX_UPDATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandProductMixUpdate.enable-exponential-backoff=${FINERACT_COMMAND_PRODUCT_MIX_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandProductMixUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_PRODUCT_MIX_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandProductMixUpdate.retryExceptions=${FINERACT_COMMAND_PRODUCT_MIX_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} + +resilience4j.retry.instances.commandProductMixDelete.max-attempts=${FINERACT_COMMAND_PRODUCT_MIX_DELETE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandProductMixDelete.wait-duration=${FINERACT_COMMAND_PRODUCT_MIX_DELETE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandProductMixDelete.enable-exponential-backoff=${FINERACT_COMMAND_PRODUCT_MIX_DELETE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandProductMixDelete.exponential-backoff-multiplier=${FINERACT_COMMAND_PRODUCT_MIX_DELETE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandProductMixDelete.retryExceptions=${FINERACT_COMMAND_PRODUCT_MIX_DELETE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} + +# floating rate + +resilience4j.retry.instances.commandFloatingRateCreate.max-attempts=${FINERACT_COMMAND_FLOATING_RATE_CREATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandFloatingRateCreate.wait-duration=${FINERACT_COMMAND_FLOATING_RATE_CREATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandFloatingRateCreate.enable-exponential-backoff=${FINERACT_COMMAND_FLOATING_RATE_CREATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandFloatingRateCreate.exponential-backoff-multiplier=${FINERACT_COMMAND_FLOATING_RATE_CREATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandFloatingRateCreate.retryExceptions=${FINERACT_COMMAND_FLOATING_RATE_CREATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} + +resilience4j.retry.instances.commandFloatingRateUpdate.max-attempts=${FINERACT_COMMAND_FLOATING_RATE_UPDATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandFloatingRateUpdate.wait-duration=${FINERACT_COMMAND_FLOATING_RATE_UPDATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandFloatingRateUpdate.enable-exponential-backoff=${FINERACT_COMMAND_FLOATING_RATE_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandFloatingRateUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_FLOATING_RATE_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandFloatingRateUpdate.retryExceptions=${FINERACT_COMMAND_FLOATING_RATE_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} # interest rate 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 000000000000..b04cb987a83a --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java @@ -0,0 +1,133 @@ +/** + * 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.io.IOException; +import java.lang.reflect.Method; +import java.util.ArrayList; +import java.util.List; +import java.util.Properties; +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(); + } + + /** + * A {@code @Retry} that names an instance nobody configured does not fail: resilience4j falls back to its own + * defaults, which retry on every exception, so a validation error is attempted three times while its neighbours + * retry only on contention. The handler then says it retries, and nothing checks that it retries on what was + * intended. + */ + @Test + void everyRetryInstanceAHandlerNamesIsConfigured() throws IOException { + var configured = new Properties(); + + try (var in = CommandHandlerRetryCoverageTest.class.getClassLoader().getResourceAsStream("application.properties")) { + assertThat(in).as("The application's properties must be on the test classpath.").isNotNull(); + configured.load(in); + } + + var unconfigured = new ArrayList(); + + for (Class handler : commandHandlers()) { + if (handler.getName().startsWith(SAMPLE_HANDLERS)) { + continue; + } + + handleMethodOf(handler).map(method -> method.getAnnotation(Retry.class)).map(Retry::name) + .filter(name -> !configured.containsKey("resilience4j.retry.instances." + name + ".retryExceptions")) + .ifPresent(name -> unconfigured.add(handler.getSimpleName() + " -> " + name)); + } + + assertThat(unconfigured) + .as("These handlers name a retry instance with no retryExceptions in application.properties, so " + + "they retry on every exception, a validation error included. Configure the instance like its neighbours.") + .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; + } +} From 71075771fa11d42cbe1ece2eb05c0ed62adc09ce Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 18:48:08 +0000 Subject: [PATCH 4/5] FINERACT-2485: Record what a command acted on and what it did Every command declares its entity and action names, in the vocabulary of m_permission, and m_command stores them in two new NOT NULL columns (rows written before are backfilled as UNKNOWN). The audit search and the checker inbox are defined in these terms, and maker-checker derives the approval permission from them, so a row without them is invisible to both. Declared as abstract methods on Command rather than an optional interface: a command that forgot them would be stored with none. The names follow m_permission, which is not always what the class name suggests (CACHE/UPDATE, BUSINESS_DATE, COLLATERAL_PRODUCT, CHARTSLAB, MEETING for attendance); notes and images compute the entity from their payload. HookableCommand becomes a marker, and a command read back from the store is a StoredCommand carrying the recorded names. Step 4 of 9 of FINERACT-2485. --- .../async/AsyncCommandDispatcherTest.java | 5 +- .../CompleteableCommandEventHandlerTest.java | 8 +-- .../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/0003_command_action_entity.xml | 46 +++++++++++++++++ .../jdbc/JdbcCommandRepositoryTest.java | 22 ++++++++ .../test/sample/command/DummyCommand.java | 13 ++++- .../sample/command/DummyErrorCommand.java | 13 ++++- .../apache/fineract/command/core/Command.java | 19 ++++++- .../command/core/HookableCommand.java | 15 +++--- .../DefaultCommandHookManagerTest.java | 7 +-- .../SynchronousCommandDispatcherTest.java | 9 ++-- .../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 ++++++-- .../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 ++++- 66 files changed, 804 insertions(+), 93 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/0003_command_action_entity.xml diff --git a/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java b/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java index a8caf6d4e0f1..5dbef5fe8afa 100644 --- a/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java +++ b/fineract-command-async/src/test/java/org/apache/fineract/command/async/AsyncCommandDispatcherTest.java @@ -33,6 +33,7 @@ import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandHookError; import org.apache.fineract.command.implementation.DefaultCommandHookManager; +import org.apache.fineract.command.test.sample.command.DummyCommand; import org.junit.jupiter.api.Test; /** @@ -62,7 +63,7 @@ void skipExecutionReturnsTheHookResponseWithoutRunningTheHandlerOrTheAfterHooks( }; var dispatcher = dispatcher(List.of(answering), List.of(ctx -> calls.add("after")), List.of()); - Object result = dispatcher.dispatch(new Command<>()).get(); + Object result = dispatcher.dispatch(new DummyCommand()).get(); assertEquals("replayed", result); assertEquals(0, handled.get()); @@ -74,7 +75,7 @@ void errorHooksGetTheExceptionTheHandlerThrewNotTheCompletionWrapper() { List errors = new CopyOnWriteArrayList<>(); var dispatcher = dispatcher(List.of(), List.of(), List.of(ctx -> errors.add(ctx.getError()))); - assertThrows(RuntimeException.class, () -> dispatcher.dispatch(new Command<>()).get()); + assertThrows(RuntimeException.class, () -> dispatcher.dispatch(new DummyCommand()).get()); assertEquals(1, errors.size()); assertSame(failure, errors.get(0)); diff --git a/fineract-command-disruptor/src/test/java/org/apache/fineract/command/disruptor/CompleteableCommandEventHandlerTest.java b/fineract-command-disruptor/src/test/java/org/apache/fineract/command/disruptor/CompleteableCommandEventHandlerTest.java index 9a53abfd30ad..6864926644bc 100644 --- a/fineract-command-disruptor/src/test/java/org/apache/fineract/command/disruptor/CompleteableCommandEventHandlerTest.java +++ b/fineract-command-disruptor/src/test/java/org/apache/fineract/command/disruptor/CompleteableCommandEventHandlerTest.java @@ -37,6 +37,8 @@ import org.apache.fineract.command.disruptor.implementation.DisruptorCommandDispatcher.CommandEvent; import org.apache.fineract.command.disruptor.implementation.DisruptorCommandDispatcher.CompleteableCommandEventHandler; import org.apache.fineract.command.implementation.DefaultCommandHookManager; +import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.data.DummyRequest; import org.junit.jupiter.api.Test; /** @@ -90,9 +92,9 @@ void aFailingBeforeHookCompletesTheFutureExceptionallyAfterTheErrorHooks() { assertEquals(0, handled.get()); } - private static CommandEvent event() { - var event = new CommandEvent(); - event.setContext(CommandContext.builder().command(new Command<>()).build()); + private static CommandEvent event() { + var event = new CommandEvent(); + event.setContext(CommandContext.builder().command(new DummyCommand()).build()); event.setFuture(new CompletableFuture<>()); return event; } 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 c25c79baa74c..39a1a92c3868 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 @@ -71,6 +71,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 000000000000..0c070ceb56e9 --- /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 9a4fe19e585e..1a47c3eb6db1 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 ac42af8aafef..749b1ba81f6f 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,5 @@ 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_command_action_entity.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_command_action_entity.xml new file mode 100644 index 000000000000..ac02900a1140 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_command_action_entity.xml @@ -0,0 +1,46 @@ + + + + + + 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/JdbcCommandRepositoryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java index d8440147e96e..750d0e7e3b7b 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java @@ -19,6 +19,7 @@ package org.apache.fineract.command.jdbc; import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.junit.jupiter.api.Assertions.assertEquals; import java.time.Instant; import lombok.extern.slf4j.Slf4j; @@ -76,4 +77,25 @@ void save() { log.info("Found command: {}", found.orElse(null)); } + + @Test + void theCommandRecordsWhatItActedOnAndWhatItDid() { + var command = new DummyCommand(); + + command.setPayload(DummyRequest.builder().content("hello").build()); + command.setCreatedAt(Instant.now()); + + var saved = commandRepository.save(commandMapper.map(command)); + var stored = commandRepository.findById(saved.getId()).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", stored.getEntityName(), "The entity the command acted on must be recorded."); + assertEquals("CREATE", stored.getActionName(), "The action it performed must be recorded."); + + var readBack = commandMapper.map(stored); + + assertEquals("DUMMY", readBack.entityName(), "A command read back must carry the names it was recorded with."); + assertEquals("CREATE", readBack.actionName()); + } } 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 14829a781dae..25487893438e 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 11e07ed05760..020637dde5c7 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 8441f3ca620b..db88938890e9 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 6af72daf36dd..286b71e3784f 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-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java b/fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java index 634dab169f3b..e5e6c6fe801f 100644 --- a/fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java +++ b/fineract-command/src/test/java/org/apache/fineract/command/DefaultCommandHookManagerTest.java @@ -24,12 +24,13 @@ import java.util.ArrayList; import java.util.List; -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; import org.apache.fineract.command.implementation.DefaultCommandHookManager; +import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.data.DummyRequest; import org.junit.jupiter.api.Test; /** @@ -109,8 +110,8 @@ private static DefaultCommandHookManager manager(List before, return new DefaultCommandHookManager(before, after, error); } - private static CommandContext context() { - return CommandContext.builder().command(new Command<>()).build(); + private static CommandContext context() { + return CommandContext.builder().command(new DummyCommand()).build(); } private CommandHookBefore before(String name) { diff --git a/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java b/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java index 54629afe06d6..d219dcf335ed 100644 --- a/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java +++ b/fineract-command/src/test/java/org/apache/fineract/command/SynchronousCommandDispatcherTest.java @@ -35,6 +35,7 @@ import org.apache.fineract.command.core.CommandState; import org.apache.fineract.command.implementation.DefaultCommandHookManager; import org.apache.fineract.command.implementation.SynchronousCommandDispatcher; +import org.apache.fineract.command.test.sample.command.DummyCommand; import org.junit.jupiter.api.Test; /** @@ -64,7 +65,7 @@ void skipExecutionReturnsTheHookResponseWithoutRunningTheHandlerOrTheAfterHooks( }; var dispatcher = dispatcher(List.of(answering, ctx -> calls.add("before")), List.of(ctx -> calls.add("after")), List.of()); - Object result = dispatcher.dispatch(new Command<>()).get(); + Object result = dispatcher.dispatch(new DummyCommand()).get(); assertEquals("replayed", result); assertEquals(0, handled.get(), "A command whose execution is skipped must not reach its handler."); @@ -79,7 +80,7 @@ void skipExecutionWithoutSkipHooksStillRunsTheRemainingBeforeHooks() { }; var dispatcher = dispatcher(List.of(answering, ctx -> calls.add("before")), List.of(ctx -> calls.add("after")), List.of()); - Object result = dispatcher.dispatch(new Command<>()).get(); + Object result = dispatcher.dispatch(new DummyCommand()).get(); assertEquals("replayed", result); assertEquals(0, handled.get()); @@ -97,7 +98,7 @@ void errorHooksRunAfterABeforeHookThatSkippedAndThrew() { List errors = new ArrayList<>(); var dispatcher = dispatcher(List.of(refusing), List.of(), List.of(ctx -> errors.add(ctx.getError()), ctx -> calls.add("error2"))); - var thrown = assertThrows(IllegalStateException.class, () -> dispatcher.dispatch(new Command<>()).get()); + var thrown = assertThrows(IllegalStateException.class, () -> dispatcher.dispatch(new DummyCommand()).get()); assertSame(refused, thrown); assertEquals(List.of(refused), errors, "The error hooks see the exception the hook threw."); @@ -112,7 +113,7 @@ void everyCallOfTheSupplierStartsFromAFreshContext() { seen.add(ctx.getResponse()); }; var dispatcher = dispatcher(List.of(recording), List.of(), List.of()); - var supplier = dispatcher.dispatch(new Command<>()); + var supplier = dispatcher.dispatch(new DummyCommand()); supplier.get(); supplier.get(); 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 a85b362973e6..11e9a2dcde07 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 a8a958894498..6b91aee79ae9 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 c42d79b2ebed..b406ad8785bb 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 5d949c37f67e..05fbd4d8269e 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 31da6d756db4..2d1e574cc183 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 c187cd4fa893..916b84a07d26 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 @@ -41,13 +41,13 @@ public void onError(CommandContext ctx) { // a command whose execution was skipped never ran, so it did not fail: the error is about the request (e.g. a // refused repeat of an idempotency key), not about a change to announce - if (ctx.isSkipExecution() || !(command instanceof HookableCommand hookable)) { + if (ctx.isSkipExecution() || !(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 b93083edd0ca..7d08b0f36a8a 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 dc6d98a7669e..c78afc865f01 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 dc251e713bae..49dfd60d02ce 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 48fdf2b61826..fe60793bbb63 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 55fe6aa322a5..7fab6659a80f 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 09fd50da3cff..135526035508 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"))); @@ -192,15 +192,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-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 face5244f81f..6e6f75f96831 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 ed94119436cc..b171d59c900e 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 d0c1c7c1b19b..a0aba017169e 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 2018da75e225..b49730471d1c 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 e510df6607cf..cb7aae60918b 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 a7c50a88cf81..fd3f12b83c6a 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 fe3ce311d9af..043a4d93a0a3 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 762135f777f4..6773b1c30a06 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 be114d1164dd..f0188e21f976 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 62cb6557753d..d58cfbf3a4e7 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 20ce42e06e28..e4790b6f4770 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 d9fb66931652..8deae856725f 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 a4cb599276aa..202466241147 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 eba27f6e03bb..2ce0e8455bc6 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 feb29e65491b..6eaf24a64bae 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 1adf4b6179e9..bf40a5f07ee4 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 1d6fa91e5c94..4258ef4b3a9c 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 facbeba45eaf..ef1b22fea840 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 f592c359fffc..9fee66bf2353 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 a0a72c6168d7..a6c9cdd2ced9 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 1486c0a6f841..6763673ba095 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 5b3cdde00578..47f75a1a89a8 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 fb62d9f9c50a..36fd33e05c04 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 5d4905b86848..403593e462e1 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 ceab67450b86..efb3c3bc8381 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 f64ab37fb1c2..43a25d8dcb49 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 b5174548afda..04319d9fc8f5 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 c9c1241484fc..d177f290ffd1 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 2df5e965c39e..b84d71f95f9f 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 69af8608c0c8..f3b4718931d9 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 861a13ede03b..e3cb4904b52d 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 13cf54c743f2..a2e46a6e86b8 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 220610791440..1f21ec305f05 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 ba97ea2f6a4f..4250030d3438 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 2671bb2f92ce..a126b8cf8c04 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 f4fd467dd7ad..06780c079b31 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 8d8f328c7529..f7be73f4e4da 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 eecf7933c2ad..bb420d052257 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 0a75f1ef5123..e763b5528765 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 944ecc0c0f0f..98e4a319c671 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 14748f6e53d43c96362ffd46a98e38153a4c0d8b Mon Sep 17 00:00:00 2001 From: Adam Saghy Date: Thu, 12 Nov 2026 18:48:08 +0000 Subject: [PATCH 5/5] FINERACT-2485: Claim idempotency keys in the command store The command store can now claim an idempotency key atomically and report what was stored for it, which the idempotency module in the next step builds on. - m_command.custom_idempotency_distinctor (NOT NULL, default '') holds what a key is unique together with, and a unique constraint on (idempotency_key, custom_idempotency_distinctor) makes a claim atomic. Rows from earlier builds that share a key keep the earliest one; the others get their id appended, so no record is deleted. - m_command.response_status_code records the status of an answer that is not the command's own result (a failure, or an answer that is not JSON). - CommandStore gains claim(), getReplayByKey(), matchesStoredRequest() and recordResponse(); every lookup by key also takes the distinctor, and IdempotencyKeyLookupCoverageTest fails the build on one that does not. A stored result that cannot be read back fails loudly instead of answering null. - Writes of the command row are retried on transient and recoverable data-access failures; a constraint violation is not retried, because the row is already there. Until the idempotency module is added, a second request with a key that is already stored is rejected by the constraint instead of being executed again. Step 5 of 9 of FINERACT-2485. Co-authored-by: Aleksandar Vidakovic --- fineract-command-jdbc/dependencies.gradle | 4 + .../command/jdbc/store/JdbcCommandStore.java | 120 ++++++ .../jdbc/store/domain/CommandEntity.java | 12 + .../store/domain/JdbcCommandRepository.java | 46 +- .../jdbc/store/mapping/JdbcCommandMapper.java | 2 + .../jdbc/store/mapping/JsonCommandMapper.java | 6 +- .../command/module-changelog-master.xml | 2 + .../parts/0004_idempotency_key_unique.xml | 82 ++++ .../parts/0005_command_response_cache.xml | 37 ++ .../CommandIdempotencyKeyMigrationTest.java | 196 +++++++++ .../IdempotencyKeyLookupCoverageTest.java | 85 ++++ .../jdbc/JdbcCommandRepositoryTest.java | 22 - .../jdbc/JdbcCommandStoreRetryTest.java | 136 ++++++ .../command/jdbc/JdbcCommandStoreTest.java | 399 ++++++++++++++++++ .../command/jdbc/RetryPolicyTest.java | 90 ++++ .../command-migration-test-changelog.xml | 77 ++++ .../test/sample/data/DummyRequest.java | 25 +- .../apache/fineract/command/core/Command.java | 15 + .../fineract/command/core/CommandReplay.java | 35 ++ .../fineract/command/core/CommandStore.java | 41 ++ .../src/main/resources/application.properties | 8 +- 21 files changed, 1411 insertions(+), 29 deletions(-) create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_idempotency_key_unique.xml create mode 100644 fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_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/IdempotencyKeyLookupCoverageTest.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 diff --git a/fineract-command-jdbc/dependencies.gradle b/fineract-command-jdbc/dependencies.gradle index 6027c1f77889..838ef8064259 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 f1869ce875f4..9f2f21136e2d 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 @@ -20,6 +20,9 @@ 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; @@ -31,15 +34,20 @@ 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.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 @@ -48,10 +56,103 @@ 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; + @Override + public Command getByKey(String key, String distinctor) { + return repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor).map(mapper::map).orElse(null); + } + + @Override + public boolean existsByKey(String key, String distinctor) { + return repository.existsByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor); + } + + @Override + public CommandReplay getReplayByKey(String key, String distinctor) { + return repository + .findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor).map(entity -> new CommandReplay(entity.getState(), + entity.getResponseStatusCode(), replayResponse(key, distinctor, 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, String distinctor, 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, distinctor).orElse(null); + } + + @Override + @Retry(name = "commandStore") + 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 {} (distinctor '{}', {} row(s))", statusCode, key, distinctor, 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 {} (distinctor '{}') with command id {}", command.getIdempotencyKey(), + command.getCustomIdempotencyDistinctor(), commandEntity.getId()); + + return true; + } catch (RuntimeException e) { + // the conflict is settled here, inside the retry, so it is never retried. What the retry does cover is a + // transient failure of the insert. Should one be reported for an insert that did commit - the database + // acknowledged it, the acknowledgement was lost - the next attempt meets this very claim and reports it as + // taken: the request is answered as a repeat of a command still running, until the claim times out. The + // command is never executed twice, which is the direction to fail in + if (isDuplicateKey(e)) { + log.debug("Idempotency key {} (distinctor '{}') is already claimed", command.getIdempotencyKey(), + command.getCustomIdempotencyDistinctor()); + + return false; + } + + throw e; + } + } + + @Override + public boolean matchesStoredRequest(String key, String distinctor, 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, distinctor) + .map(stored -> stored.equals(objectMapper.writeValueAsString(jsonMapper.map(payload)))).orElse(false); + } + @Override @Retry(name = "commandStore", fallbackMethod = "fallback") public void store(CommandContext ctx) { @@ -86,6 +187,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())) { @@ -103,6 +212,17 @@ void onStartup() { } } + // 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 { var file = Path .of(properties.getFileDeadLetterQueuePath(), 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 39a1a92c3868..afa37fa12901 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; @@ -71,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; @@ -80,6 +84,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 dcec7c4816ac..9f6d672daf7c 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,12 +19,54 @@ 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 { - 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. + * + *

+ * 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 custom_idempotency_distinctor = :distinctor AND response IS NULL + """) + int updateResponse(@Param("idempotencyKey") String idempotencyKey, @Param("distinctor") String distinctor, + @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 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 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 1a47c3eb6db1..86f52168d6b3 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/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 faaa5369de8f..1e3290430ce5 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 749b1ba81f6f..1654b17c2adc 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,4 +25,6 @@ + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_idempotency_key_unique.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_idempotency_key_unique.xml new file mode 100644 index 000000000000..c08a169992ca --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_idempotency_key_unique.xml @@ -0,0 +1,82 @@ + + + + + + What an idempotency key is unique together with, as the configured distinctor 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 unique constraint below compares two empty + values as equal rather than treating two nulls as distinct. + + + + + + + + + + Make idempotency keys unique, together with their distinctor, 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). + + + + + 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 + ) + + + + + + + + + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_response_cache.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_response_cache.xml new file mode 100644 index 000000000000..d6988b9756dd --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_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 000000000000..ca1e58068c25 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java @@ -0,0 +1,196 @@ +/** + * 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."); + + // 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."); + } + + rollbackUniqueConstraint(container, context); + + try (var connection = connect(container)) { + insert(connection, 102, "KEEP-1"); + assertEquals(2, count(connection, "idempotency_key = 'KEEP-1' AND custom_idempotency_distinctor = ''"), + "After rollback the same key and distinctor 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, so this count has to grow with every changeset + * added after the constraint. + */ + 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, 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 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/IdempotencyKeyLookupCoverageTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java new file mode 100644 index 000000000000..c74480f633ef --- /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/JdbcCommandRepositoryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java index 750d0e7e3b7b..d8440147e96e 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java @@ -19,7 +19,6 @@ package org.apache.fineract.command.jdbc; import static org.apache.fineract.command.core.CommandState.ERROR; -import static org.junit.jupiter.api.Assertions.assertEquals; import java.time.Instant; import lombok.extern.slf4j.Slf4j; @@ -77,25 +76,4 @@ void save() { log.info("Found command: {}", found.orElse(null)); } - - @Test - void theCommandRecordsWhatItActedOnAndWhatItDid() { - var command = new DummyCommand(); - - command.setPayload(DummyRequest.builder().content("hello").build()); - command.setCreatedAt(Instant.now()); - - var saved = commandRepository.save(commandMapper.map(command)); - var stored = commandRepository.findById(saved.getId()).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", stored.getEntityName(), "The entity the command acted on must be recorded."); - assertEquals("CREATE", stored.getActionName(), "The action it performed must be recorded."); - - var readBack = commandMapper.map(stored); - - assertEquals("DUMMY", readBack.entityName(), "A command read back must carry the names it was recorded with."); - assertEquals("CREATE", readBack.actionName()); - } } 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 000000000000..d133d13f0827 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java @@ -0,0 +1,136 @@ +/** + * 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(), 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(), 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 TestCommand(); + + 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); + } + } + + /** 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 new file mode 100644 index 000000000000..419542994f4c --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -0,0 +1,399 @@ +/** + * 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 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."); + 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()) && "".equals(e.getCustomIdempotencyDistinctor())).count(), + "Only one command row may exist per idempotency key and distinctor."); + } + + @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."); + } + + @Test + public void theCommandRecordsWhatItActedOnAndWhatItDid() { + var key = UUID.randomUUID().toString(); + + store.claim(command(key, "hello")); + + 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 + 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(); + } + + /** 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 000000000000..3ed900318d29 --- /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 000000000000..b8a6d5982d96 --- /dev/null +++ b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 df9d4ee2cba0..8e0a2d0fd01a 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/Command.java b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java index db88938890e9..1e66d0d00b18 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/CommandReplay.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java new file mode 100644 index 000000000000..1840b5b391c0 --- /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 da1106b19dee..c465625a44f6 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,5 +20,46 @@ public interface CommandStore { + /* + * 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, String distinctor); + + /** + * @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, 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, String distinctor, int statusCode, String body); + + /** + * 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. A conflict - the key is already claimed - is the + * answer, not a failure: it must be reported as {@code false}, never retried and never swallowed. A transient + * failure of the write itself may be retried. + * + * @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, String distinctor, Object payload); + void store(CommandContext ctx); } diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index f2a7d9f01fa1..b1dda9394edc 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -948,7 +948,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.