diff --git a/build.gradle b/build.gradle index ab257152a0f..9d9d9dce398 100644 --- a/build.gradle +++ b/build.gradle @@ -33,6 +33,7 @@ buildscript { 'fineract-command-audit', 'fineract-command-async', 'fineract-command-disruptor', + 'fineract-command-idempotency', 'fineract-accounting', 'fineract-provider', 'fineract-branch', @@ -73,6 +74,7 @@ buildscript { 'fineract-command', 'fineract-command-jdbc', 'fineract-command-audit', + 'fineract-command-idempotency', 'fineract-accounting', 'fineract-provider', 'fineract-investor', diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java new file mode 100644 index 00000000000..8fd93a922a6 --- /dev/null +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.async; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class AsyncCommandConstants { + + private AsyncCommandConstants() {} + + public static final String COMMAND_ASYNC_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".async"; + public static final String COMMAND_ASYNC_PROPERTY_ENABLED = COMMAND_ASYNC_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_ASYNC_BASE_PACKAGE = "org.apache.fineract.command.async.implementation"; +} diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java index 832318ed96d..d1d5d7b348d 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/AsyncCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.async; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import java.time.Duration; @@ -33,7 +35,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.async") +@ConfigurationProperties(prefix = COMMAND_ASYNC_PROPERTIES_PREFIX) public final class AsyncCommandProperties implements Serializable { @Serial diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java index 7999af97c5b..122f61a26f0 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/implementation/AsyncCommandDispatcher.java @@ -19,7 +19,9 @@ package org.apache.fineract.command.async.implementation; import static java.util.Objects.requireNonNull; -import static java.util.concurrent.TimeUnit.SECONDS; +import static java.util.concurrent.TimeUnit.MILLISECONDS; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTY_ENABLED; +import static org.apache.fineract.command.core.CommandState.PROCESSED; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; @@ -27,7 +29,9 @@ import java.util.function.Supplier; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.async.AsyncCommandProperties; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.core.CommandHandlerManager; import org.apache.fineract.command.core.CommandHookManager; @@ -38,34 +42,45 @@ @Slf4j @RequiredArgsConstructor @Component -@ConditionalOnProperty(value = "fineract.command.async.enabled", havingValue = "true") +@ConditionalOnProperty(value = COMMAND_ASYNC_PROPERTY_ENABLED, havingValue = "true") public class AsyncCommandDispatcher implements CommandDispatcher { private final CommandHandlerManager handlerManager; private final CommandHookManager hookManager; + private final AsyncCommandProperties properties; @Override public Supplier dispatch(final Command command) { requireNonNull(command, "Command must not be null"); + final var ctx = CommandContext.builder().command(command).build(); + CompletableFuture future = CompletableFuture.supplyAsync(() -> { - hookManager.before(command); + hookManager.before(ctx); + + if (ctx.isSkipExecution()) { + return ctx.getResponse(); + } RES response = handlerManager.handle(command); - hookManager.after(command, response); + ctx.setResponse(response); + ctx.setState(PROCESSED); - return response; + hookManager.after(ctx); + + return ctx.getResponse(); }).whenComplete((response, t) -> { if (t != null) { - hookManager.error(command, t); + ctx.setError(t); + + hookManager.error(ctx); } }); return () -> { try { - // TODO: make this configurable - return future.get(3, SECONDS); + return future.get(properties.getTimeout().toMillis(), MILLISECONDS); } catch (InterruptedException | ExecutionException | TimeoutException e) { throw new RuntimeException(e); } diff --git a/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java b/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java index d4410fb07fc..2f112586b5b 100644 --- a/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java +++ b/fineract-command-async/src/main/java/org/apache/fineract/command/async/starter/AsyncCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.async.starter; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_BASE_PACKAGE; +import static org.apache.fineract.command.async.AsyncCommandConstants.COMMAND_ASYNC_PROPERTY_ENABLED; + import org.apache.fineract.command.async.AsyncCommandProperties; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -26,6 +29,6 @@ @AutoConfiguration @EnableConfigurationProperties(AsyncCommandProperties.class) -@ComponentScan("org.apache.fineract.command.async.implementation") -@ConditionalOnProperty(value = "fineract.command.async.enabled", havingValue = "true") +@ComponentScan(COMMAND_ASYNC_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_ASYNC_PROPERTY_ENABLED, havingValue = "true") public class AsyncCommandAutoConfiguration {} diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java index 5ba7b115822..98fb754aa35 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandConstants.java @@ -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 12995780098..75a46145a23 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/AuditCommandProperties.java @@ -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 00000000000..38af9182f4c --- /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 529ed034961..d871b7829d5 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookAfter.java @@ -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 524f47537e0..aac22252608 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookBefore.java @@ -18,13 +18,14 @@ */ package org.apache.fineract.command.audit.hook; -import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_HOOK_AUDIT_BEFORE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_HOOK_BEFORE; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED; import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandStore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -34,20 +35,24 @@ @Slf4j @RequiredArgsConstructor @Component -@Order(COMMAND_HOOK_AUDIT_BEFORE) -@ConditionalOnProperty(value = "fineract.command.hooks.audit-pre", havingValue = "true") -final class AuditCommandHookBefore implements CommandHookBefore { +@Order(COMMAND_AUDIT_HOOK_BEFORE) +@ConditionalOnProperty(value = COMMAND_AUDIT_PROPERTY_HOOK_PRE_ENABLED, havingValue = "true", matchIfMissing = true) +final class AuditCommandHookBefore implements CommandHookBefore { private final CommandStore store; @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { final var now = Instant.now(); + var command = ctx.getCommand(); + command.setExecutedByUsername(command.getInitiatedByUsername()); command.setUpdatedAt(now); command.setExecutedAt(now); - store.store(command, null, UNDER_PROCESSING); + ctx.setState(UNDER_PROCESSING); + + store.store(ctx); } } diff --git a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java index fe1d2b6376a..dff61cf3520 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/hook/AuditCommandHookError.java @@ -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 7b186c6c4a5..c11c5c49fdc 100644 --- a/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java +++ b/fineract-command-audit/src/main/java/org/apache/fineract/command/audit/starter/AuditCommandAutoConfiguration.java @@ -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 00000000000..82b3435b7dc --- /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 56b407045f3..6041b23e1fe 100644 --- a/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports +++ b/fineract-command-audit/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports @@ -1 +1,2 @@ -org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration \ No newline at end of file +org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration +org.apache.fineract.command.audit.starter.AuditCommandPropertyCheckAutoConfiguration \ No newline at end of file diff --git a/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java b/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java new file mode 100644 index 00000000000..ece385ac7dd --- /dev/null +++ b/fineract-command-audit/src/test/java/org/apache/fineract/command/audit/check/AuditCommandPropertyCheckTest.java @@ -0,0 +1,103 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.audit.check; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; + +import org.apache.fineract.command.audit.starter.AuditCommandAutoConfiguration; +import org.apache.fineract.command.audit.starter.AuditCommandPropertyCheckAutoConfiguration; +import org.apache.fineract.command.core.CommandHookAfter; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.core.CommandHookError; +import org.apache.fineract.command.core.CommandStore; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.boot.test.system.CapturedOutput; +import org.springframework.boot.test.system.OutputCaptureExtension; + +@ExtendWith(OutputCaptureExtension.class) +class AuditCommandPropertyCheckTest { + + private final ApplicationContextRunner runner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(AuditCommandPropertyCheckAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)); + + @Test + void theCheckIsRegisteredSoThatItCanActuallyReport(CapturedOutput output) { + runner.run(context -> { + assertThat(context).hasSingleBean(AuditCommandPropertyCheck.class); + assertThat(output).contains("Audit pre command hook enabled."); + }); + } + + @Test + void auditingIsOnWhenNothingIsConfigured(CapturedOutput output) { + // losing the audit trail must be a decision, not the consequence of an unset property + runner.run(context -> { + assertThat(output).contains("Audit pre command hook enabled."); + assertThat(output).contains("Audit post command hook enabled."); + assertThat(output).contains("Audit error command hook enabled."); + assertThat(output).doesNotContain("disabled!"); + }); + } + + @Test + void anExplicitlyDisabledHookIsReportedAsDisabled(CapturedOutput output) { + runner.withPropertyValues("fineract.command.audit.hook-pre-enabled=false", "fineract.command.audit.hook-post-enabled=false", + "fineract.command.audit.hook-error-enabled=false").run(context -> { + assertThat(output).contains("Audit pre command hook disabled!"); + assertThat(output).contains("Audit post command hook disabled!"); + assertThat(output).contains("Audit error command hook disabled!"); + assertThat(output).doesNotContain("command hook enabled."); + }); + } + + @Test + void anExplicitlyDisabledModuleIsReportedAsDisabled(CapturedOutput output) { + runner.withPropertyValues("fineract.command.audit.enabled=false").run(context -> { + assertThat(context).hasSingleBean(AuditCommandPropertyCheck.class); + assertThat(output).contains("Command audit is disabled!"); + }); + } + + @Test + void theReportedDefaultsMatchTheHooksThatAreActuallyCreated() { + // guards against the properties class describing behaviour the application does not have + new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(AuditCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)).run(context -> { + assertThat(context).hasSingleBean(CommandHookBefore.class); + assertThat(context).hasSingleBean(CommandHookAfter.class); + assertThat(context).hasSingleBean(CommandHookError.class); + }); + } + + @Test + void noHooksAreCreatedWhenTheModuleIsExplicitlyDisabled() { + new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(AuditCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)).withPropertyValues("fineract.command.audit.enabled=false") + .run(context -> { + assertThat(context).doesNotHaveBean(CommandHookBefore.class); + assertThat(context).doesNotHaveBean(CommandHookAfter.class); + assertThat(context).doesNotHaveBean(CommandHookError.class); + }); + } +} diff --git a/fineract-command-audit/src/test/resources/application-test.properties b/fineract-command-audit/src/test/resources/application-test.properties index e160de083a8..5611a2cb03b 100644 --- a/fineract-command-audit/src/test/resources/application-test.properties +++ b/fineract-command-audit/src/test/resources/application-test.properties @@ -21,6 +21,6 @@ debug=true fineract.command.enabled=true fineract.command.audit.enabled=true -fineract.command.hooks.audit-pre=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE:true} -fineract.command.hooks.audit-post=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST:true} -fineract.command.hooks.audit-error=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR:true} +fineract.command.audit.hook-pre-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE_ENABLED:true} +fineract.command.audit.hook-post-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED:true} +fineract.command.audit.hook-error-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR_ENABLED:true} diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java new file mode 100644 index 00000000000..f478fcc93f8 --- /dev/null +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.disruptor; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class DisruptorCommandConstants { + + private DisruptorCommandConstants() {} + + public static final String COMMAND_DISRUPTOR_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".disruptor"; + public static final String COMMAND_DISRUPTOR_PROPERTY_ENABLED = COMMAND_DISRUPTOR_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_DISRUPTOR_BASE_PACKAGE = "org.apache.fineract.command.disruptor.implementation"; +} diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java index 130990a8564..aeda9dca444 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/DisruptorCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.disruptor; +import static org.apache.fineract.command.disruptor.DisruptorCommandConstants.COMMAND_DISRUPTOR_PROPERTIES_PREFIX; + import com.lmax.disruptor.dsl.ProducerType; import java.io.Serial; import java.io.Serializable; @@ -33,7 +35,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.disruptor") +@ConfigurationProperties(prefix = COMMAND_DISRUPTOR_PROPERTIES_PREFIX) public final class DisruptorCommandProperties implements Serializable { @Serial diff --git a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java index 59f48211ad0..971251d4a11 100644 --- a/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java +++ b/fineract-command-disruptor/src/main/java/org/apache/fineract/command/disruptor/implementation/DisruptorCommandDispatcher.java @@ -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 + * A claim that is never resolved - the process died between claiming the key and recording the outcome, or the + * store gave up after its retries - would otherwise answer every repeat {@code 425 Too Early} for ever, and a + * client following that advice retries for ever. Long enough that a slow command is not declared dead: the key is + * never re-executed, but a repeat past this point is refused, and the caller has to use a new one. + * + *

+ * Zero or empty switches the timeout off: a repeat of an unfinished claim is then answered {@code 425 Too Early} + * for as long as it stays unfinished, as in the legacy command processing. A negative value is refused at startup. + */ + @Builder.Default + private Duration claimTimeout = Duration.ofMinutes(10); + + /** + * What an idempotency key is unique together with. {@code ENTITY_NAME_AND_ACTION_NAME}, the default, scopes it to + * the command's entity and action, the way the legacy command processing does; {@code NONE} makes a key unique per + * tenant across all commands. See {@link CustomIdempotencyDistinctorType}. + */ + @Builder.Default + private CustomIdempotencyDistinctorType customDistinctor = CustomIdempotencyDistinctorType.ENTITY_NAME_AND_ACTION_NAME; +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java new file mode 100644 index 00000000000..a4c6cf3a270 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/RecoverableErrorKey.java @@ -0,0 +1,64 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.HexFormat; + +/** + * The key a failed command is moved to when its failure is recoverable, so that its original key is free for a retry. + * + *

+ * The same scheme the legacy command processing uses: {@code _RE}, where {@code } is the command's own row + * id, so the moved key is unique and still traceable to the original. When that would not fit the column, the key part + * is replaced by the first {@value #HASH_LENGTH} hex characters of its SHA-256 hash, which always fits. + */ +public final class RecoverableErrorKey { + + public static final String SUFFIX = "_RE"; + + /** The width of {@code m_command.idempotency_key}. */ + public static final int KEY_LENGTH = 255; + + static final int HASH_LENGTH = 40; + + private RecoverableErrorKey() {} + + public static String movedKey(String idempotencyKey, long commandId) { + var suffix = SUFFIX + commandId; + + if (idempotencyKey.length() + suffix.length() <= KEY_LENGTH) { + return idempotencyKey + suffix; + } + + return hash(idempotencyKey) + suffix; + } + + private static String hash(String idempotencyKey) { + try { + var digest = MessageDigest.getInstance("SHA-256").digest(idempotencyKey.getBytes(StandardCharsets.UTF_8)); + + return HexFormat.of().formatHex(digest).substring(0, HASH_LENGTH); + } catch (NoSuchAlgorithmException e) { + throw new IllegalStateException("SHA-256 is not available", e); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.java new file mode 100644 index 00000000000..0c657f0f84c --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheck.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.idempotency.check; + +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED; +import static org.apache.fineract.command.audit.AuditCommandConstants.COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; + +import jakarta.annotation.PostConstruct; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.audit.AuditCommandProperties; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.stereotype.Component; + +/** + * Refuses to start an application that has idempotency switched on and auditing switched off. + * + *

+ * Claiming an idempotency key writes the command row, but nothing in this module ever writes it again: it is the audit + * hooks that move a claimed command out of {@code UNDER_PROCESSING} and store the result a repeat is answered with. Run + * idempotency without them and the first request for a key succeeds, the row stays {@code UNDER_PROCESSING} for ever, + * and every repeat of that key is answered {@code 425 Too Early} - the key is poisoned, silently, and only from the + * second request onwards. That is worth failing a startup over rather than warning about. + * + *

+ * Switching auditing on as a whole is not enough: the after hook records a command that completed and the error hook + * one that failed, and each can be switched off on its own. Without the after hook every successful command stays + * claimed; without the error hook every failed one does. Either way a repeat is told to retry until the claim times + * out, and is then told the command never finished - which, for a command that completed, is untrue. The before hook is + * not required: claiming the key has already written the row it would write. + */ +@Slf4j +@RequiredArgsConstructor +@Component +final class IdempotencyCommandPropertyCheck { + + private final IdempotencyCommandProperties idempotency; + + private final AuditCommandProperties audit; + + @PostConstruct + void check() { + if (!Boolean.TRUE.equals(idempotency.getEnabled())) { + log.info("Command idempotency is disabled: commands are still audited, but no idempotency key is read and " + + "a repeated request is executed again rather than replayed."); + + return; + } + + if (!Boolean.TRUE.equals(audit.getEnabled())) { + throw new IllegalStateException("Command idempotency is enabled but command auditing is not: " + COMMAND_AUDIT_PROPERTY_ENABLED + + " must be true. Idempotency relies on the audit hooks to record how a " + + "command finished; without them every repeat of an idempotency key would be answered 425 Too Early for " + + "ever. Enable auditing, or set " + COMMAND_IDEMPOTENCY_PROPERTY_ENABLED + "=false."); + } + + requireHook(COMMAND_AUDIT_PROPERTY_HOOK_POST_ENABLED, audit.getHookPostEnabled(), "completed"); + requireHook(COMMAND_AUDIT_PROPERTY_HOOK_ERROR_ENABLED, audit.getHookErrorEnabled(), "failed"); + + var claimTimeout = idempotency.getClaimTimeout(); + + if (claimTimeout != null && claimTimeout.isNegative()) { + // a negative age is always exceeded, so every unfinished claim - including one still running - would be + // declared abandoned; zero is how the timeout is switched off + throw new IllegalStateException("fineract.command.idempotency.claim-timeout must not be negative, but is " + claimTimeout + + ". Use 0 to switch the timeout off."); + } + + if (claimTimeout == null || claimTimeout.isZero()) { + log.info("Command idempotency claim timeout is off: a repeat of an unfinished command is answered 425 Too Early for as " + + "long as it stays unfinished."); + } + + log.info("Command idempotency is enabled."); + } + + private static void requireHook(String property, Boolean enabled, String outcome) { + if (!Boolean.TRUE.equals(enabled)) { + throw new IllegalStateException("Command idempotency is enabled but " + property + " is not: it is the audit hook that " + + "records a command that " + outcome + ", so without it such a command stays under processing and every " + + "repeat of its idempotency key is refused instead of being answered. Enable the hook, or set " + + COMMAND_IDEMPOTENCY_PROPERTY_ENABLED + "=false."); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java new file mode 100644 index 00000000000..b378064a528 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctor.java @@ -0,0 +1,52 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import org.apache.fineract.command.core.Command; + +/** + * Decides what an idempotency key is unique together with. + * + *

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

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

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

+ * This is how the legacy command processing scopes a key, so the same key may be used once per entity and action: a key + * reused on a different endpoint is executed as a new command rather than refused. + */ +public final class EntityAndActionNameCustomIdempotencyDistinctor implements CustomIdempotencyDistinctor { + + public static final String SEPARATOR = "|"; + + @Override + public String distinctorFor(Command command) { + return command.entityName() + SEPARATOR + command.actionName(); + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java new file mode 100644 index 00000000000..6720f1fcbd3 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/distinctor/NoCustomIdempotencyDistinctor.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import org.apache.fineract.command.core.Command; + +/** + * Distinguishes nothing: every command gets the empty string, so an idempotency key is unique per tenant across all + * commands, and a key reused on a different endpoint is refused rather than executed. + */ +public final class NoCustomIdempotencyDistinctor implements CustomIdempotencyDistinctor { + + public static final String NONE = ""; + + @Override + public String distinctorFor(Command command) { + return NONE; + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java new file mode 100644 index 00000000000..d717e40f32a --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHook.java @@ -0,0 +1,265 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; + +import java.time.Instant; +import java.util.Map; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.core.CommandReplay; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.exception.CommandIdempotencyConflictException; +import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; +import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; +import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; +import org.apache.fineract.command.util.ServletHeaderUtil; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.context.request.RequestAttributes; +import org.springframework.web.context.request.RequestContextHolder; + +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_CHECK_BEFORE) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) +final class IdempotencyCheckCommandHook implements CommandHookBefore { + + private final CommandStore store; + + private final IdempotencyCommandProperties properties; + + private final CustomIdempotencyDistinctor distinctor; + + @Override + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + var key = command.getIdempotencyKey(); + + if (StringUtils.isEmpty(key)) { + return; + } + + // the key is unique together with its distinctor, so the distinctor has to be on the command before it is + // claimed + var distinctorValue = distinctorFor(command); + + command.setCustomIdempotencyDistinctor(distinctorValue); + + // claiming the key is what detects duplicates: the unique constraint means exactly one concurrent request can + // win, whereas a read-only check followed by execution lets every racer through + if (store.claim(command)) { + rememberClaimForResponseCapture(key, distinctorValue); + + return; + } + + // the command is never executed again, so it is not audited again either; the claimed row already owns this key + ctx.setSkipExecution(true); + ctx.setSkipHooks(true); + + var replay = replayFor(key, distinctorValue); + + log.warn("Duplicate idempotency key detected: {} (distinctor = '{}', state = {}, user = {}, ip = {})", key, distinctorValue, + replay.state(), command.getInitiatedByUsername(), command.getIpAddress()); + + if (UNDER_PROCESSING.equals(replay.state())) { + if (abandoned(replay)) { + throw abandonedClaim(key, replay); + } + + // the original has not finished, so there is nothing to replay yet and retrying is the right thing to do + throw new CommandIdempotencyInProgressException(key, replay.response()); + } + + if (!store.matchesStoredRequest(key, distinctorValue, command.getPayload())) { + // replaying here would answer a question that was never asked + throw new CommandIdempotencyConflictException(key, null); + } + + if (ERROR.equals(replay.state())) { + // a repeat of a failed command fails exactly the way the original did + throw new CommandIdempotencyFailedException(key, replay.statusCode(), replay.response()); + } + + if (PROCESSED.equals(replay.state())) { + replayProcessed(ctx, key, replay); + + return; + } + + throw new CommandIdempotencyConflictException(key, replay.response()); + } + + /** + * Reads what was stored for a key, turning a result that cannot be reconstructed into a rejection. + * + *

+ * A stored result that will not rehydrate - a type that has been renamed or removed since, a field that no longer + * deserialises - leaves the original answer unreachable. Letting that surface as a server error would say the + * request failed, and answering with an empty body would say it succeeded with no content; both are untrue. The key + * has been used and its answer cannot be produced, so the request is refused and told why. + * + *

+ * Only a command that completed stores a result of its own, so a result that will not rehydrate means the command + * was carried out. The answer says so, and must not suggest sending it again under a new key: that would carry it + * out a second time, which is the duplicate this mechanism exists to prevent. + */ + private CommandReplay replayFor(String key, String distinctorValue) { + try { + return store.getReplayByKey(key, distinctorValue); + } catch (RuntimeException e) { + log.error("Cannot reconstruct the stored result for idempotency key {}", key, e); + + throw new CommandIdempotencyConflictException(key, + Map.of("idempotencyKey", key, "error", + "The command sent with this idempotency key was carried out, but the result stored for it cannot " + + "be reconstructed, so the original answer cannot be replayed. Do not send it again " + + "under a new idempotency key: that would carry it out a second time."), + e); + } + } + + /** + * Whether a claim has been unfinished for longer than any command should take. + * + *

+ * A command that is recorded as running has either not finished yet or never will: the process died between + * claiming the key and recording the outcome, or the store gave up writing it. Nothing distinguishes the two from + * the row, so age stands in for it. Treated as abandoned only well past the point where a command could still be + * working, because the cost of being wrong is telling a caller their request failed while it is still running. + * + *

+ * With no timeout configured - zero or empty - no claim is ever treated as abandoned, and a repeat of an unfinished + * one is answered {@code 425 Too Early} for as long as it stays unfinished, which is what the legacy command + * processing does. + */ + private boolean abandoned(CommandReplay replay) { + var claimedAt = replay.claimedAt(); + var timeout = properties.getClaimTimeout(); + + if (timeout == null || timeout.isZero()) { + return false; + } + + return claimedAt != null && claimedAt.isBefore(Instant.now().minus(timeout)); + } + + /** + * Refuses a repeat whose original will never finish. + * + *

+ * The alternative - answering {@code 425 Too Early} as for a command that is genuinely still running - tells the + * caller to come back, and nothing will ever change, so they retry for ever. The key is deliberately not released + * for another attempt: the first command may have reached the database before whatever stopped it, and running it + * again is the duplicate this whole mechanism exists to prevent. + */ + private CommandIdempotencyConflictException abandonedClaim(String key, CommandReplay replay) { + log.error("Idempotency key {} has been under processing since {}, longer than the {} it is given; the command that " + + "claimed it never recorded an outcome", key, replay.claimedAt(), properties.getClaimTimeout()); + + return new CommandIdempotencyConflictException(key, + Map.of("idempotencyKey", key, "error", + "The command that claimed this idempotency key never finished, so its answer cannot be produced and the " + + "key cannot be reused. Whether it took effect has to be established before retrying, and a " + + "retry needs a new idempotency key.")); + } + + /** + * Answers a repeat of a command that completed. + * + *

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

+ * Only a command that stored no result of its own falls back to the answer that was captured as it went out, and + * that is text rather than an object, so it has to be thrown with the status recorded alongside it. + */ + private void replayProcessed(CommandContext ctx, String key, CommandReplay replay) { + var response = replay.response(); + + if (response == null || response instanceof String) { + throw new CommandIdempotencyProcessedException(key, replay.statusCode(), response); + } + + markServedFromCache(key); + + ctx.setResponse(response); + } + + /** + * The replay header is set here rather than by an exception mapper, because a replay answered from the command's + * own result never reaches one - it leaves through the ordinary return path. + */ + private static void markServedFromCache(String key) { + if (!ServletHeaderUtil.setResponseHeader(IDEMPOTENT_CACHE_HEADER, "true")) { + log.warn("Replaying idempotency key {} outside an HTTP response, so it is not marked as served from cache", key); + } + } + + private static void rememberClaimForResponseCapture(String key, String distinctorValue) { + var attributes = RequestContextHolder.getRequestAttributes(); + + if (attributes != null) { + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, key, RequestAttributes.SCOPE_REQUEST); + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE, distinctorValue, RequestAttributes.SCOPE_REQUEST); + } + } + + /** + * The configured distinctor's value for this command, refused here rather than by the database when it cannot be + * stored: the column does not take {@code null}, and a value longer than the column would fail the claim with a + * data error instead of a message that names the distinctor. + */ + private String distinctorFor(Command command) { + var value = distinctor.distinctorFor(command); + + if (value == null) { + throw new IllegalStateException(distinctor.getClass().getName() + " returned no idempotency distinctor for " + + command.getClass().getName() + "; return the empty string to distinguish nothing."); + } + + if (value.length() > CustomIdempotencyDistinctor.MAX_LENGTH) { + throw new IllegalStateException( + distinctor.getClass().getName() + " returned an idempotency distinctor of " + value.length() + " characters for " + + command.getClass().getName() + "; at most " + CustomIdempotencyDistinctor.MAX_LENGTH + " can be stored."); + } + + return value; + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java new file mode 100644 index 00000000000..5c7fd9414e0 --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyKeyHeaderCommandHook.java @@ -0,0 +1,53 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE; +import static org.apache.fineract.command.util.ServletHeaderUtil.getHeader; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookBefore; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; + +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_HEADERS_BEFORE) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_KEY_HEADER_PRE, havingValue = "true", matchIfMissing = true) +final class IdempotencyKeyHeaderCommandHook implements CommandHookBefore { + + private final IdempotencyCommandProperties properties; + + @Override + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + + if (StringUtils.isEmpty(command.getIdempotencyKey())) { + // header only: an idempotency key in the query string would be copied into access and proxy logs + command.setIdempotencyKey(getHeader(properties.getKeyHeaderName(), false)); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java new file mode 100644 index 00000000000..1b6cc39461a --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHook.java @@ -0,0 +1,124 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_RECOVERABLE_ERROR; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; + +import java.util.concurrent.CompletionException; +import java.util.concurrent.ExecutionException; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.apache.commons.lang3.StringUtils; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandHookError; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.apache.fineract.command.idempotency.RecoverableErrorKey; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.context.request.RequestAttributes; +import org.springframework.web.context.request.RequestContextHolder; + +/** + * Releases the idempotency key of a command that failed recoverably, so that a retry under the same key executes the + * command again instead of being answered with the failure. + * + *

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

+ * Anything that goes wrong here leaves the key where it is, which is what happens to every other failure: the retry is + * answered with the stored failure. Failing the request over it would replace the error the client needs to see. + */ +@Slf4j +@RequiredArgsConstructor +@Component +@Order(COMMAND_IDEMPOTENCY_HOOK_RECOVERABLE_ERROR) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) +final class IdempotencyRecoverableErrorCommandHook implements CommandHookError { + + private final CommandStore store; + + private final RecoverableCommandErrorClassifier classifier; + + @Override + public void onError(CommandContext ctx) { + var command = ctx.getCommand(); + var key = command.getIdempotencyKey(); + + // a repeat that was refused never claimed the key, and a command without a key or a row has nothing to release + if (ctx.isSkipExecution() || StringUtils.isEmpty(key) || command.getCommandId() == null) { + return; + } + + try { + if (!classifier.isRecoverable(unwrap(ctx.getError()))) { + return; + } + + var distinctor = command.getCustomIdempotencyDistinctor(); + var movedKey = RecoverableErrorKey.movedKey(key, command.getCommandId()); + + if (store.existsByKey(movedKey, distinctor)) { + // only possible when a client sent that exact key itself; storing the failure under the original key + // is the same thing the legacy processing does then + log.warn("Idempotency key {} is already taken, keeping the recoverable failure under the original key {}", movedKey, key); + + return; + } + + command.setIdempotencyKey(movedKey); + rememberMovedKeyForResponseCapture(key, movedKey); + + log.info("Command {} failed recoverably; idempotency key {} is released and the failure is kept under {}", + command.getCommandId(), key, movedKey); + } catch (RuntimeException e) { + command.setIdempotencyKey(key); + + log.warn("Could not release idempotency key {} after a recoverable error, keeping the failure under it", key, e); + } + } + + /** The dispatchers that run commands elsewhere hand the failure back wrapped. */ + private static Throwable unwrap(Throwable error) { + var current = error; + + while ((current instanceof CompletionException || current instanceof ExecutionException) && current.getCause() != null) { + current = current.getCause(); + } + + return current; + } + + /** The response capture filter records the answer against the claimed key, which is now the moved one. */ + private static void rememberMovedKeyForResponseCapture(String key, String movedKey) { + var attributes = RequestContextHolder.getRequestAttributes(); + + if (attributes != null + && key.equals(attributes.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, RequestAttributes.SCOPE_REQUEST))) { + attributes.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, movedKey, RequestAttributes.SCOPE_REQUEST); + } + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java new file mode 100644 index 00000000000..439125379ea --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandAutoConfiguration.java @@ -0,0 +1,82 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.starter; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_ENABLED; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE; + +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; +import org.apache.fineract.command.idempotency.web.IdempotencyResponseCaptureFilter; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.boot.web.servlet.FilterRegistrationBean; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.ComponentScan; +import org.springframework.core.Ordered; + +@AutoConfiguration +@EnableConfigurationProperties({ IdempotencyCommandProperties.class }) +@ComponentScan({ COMMAND_IDEMPOTENCY_HOOK_BASE_PACKAGE, COMMAND_IDEMPOTENCY_WEB_BASE_PACKAGE }) +@ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_ENABLED, havingValue = "true", matchIfMissing = true) +public class IdempotencyCommandAutoConfiguration { + + /** + * Fills in what a command could not record about its own answer: the status it was sent with, always, and the body + * itself only when the command stored no result of its own - a failure, or an answer that is not JSON. Ordered + * early so that it sees the response as the client will, and it steps aside entirely for requests that carry no + * key. + */ + @Bean + @ConditionalOnProperty(value = COMMAND_IDEMPOTENCY_PROPERTY_HOOK_CHECK_PRE, havingValue = "true", matchIfMissing = true) + FilterRegistrationBean idempotencyResponseCaptureFilter(CommandStore store, + IdempotencyCommandProperties properties) { + var registration = new FilterRegistrationBean<>(new IdempotencyResponseCaptureFilter(store, properties)); + + registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 100); + + return registration; + } + + /** + * What an idempotency key is unique together with, as {@code fineract.command.idempotency.custom-distinctor} + * selects. Backs off for a distinctor the application defines itself. + */ + @Bean + @ConditionalOnMissingBean + CustomIdempotencyDistinctor customIdempotencyDistinctor(IdempotencyCommandProperties properties) { + return properties.getCustomDistinctor().create(); + } + + /** + * Treats no failure as recoverable, so every failure keeps its key, until the application says otherwise by + * defining its own classifier - Fineract does, with the rules of the legacy command processing. + */ + @Bean + @ConditionalOnMissingBean + RecoverableCommandErrorClassifier recoverableCommandErrorClassifier() { + return error -> false; + } +} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java new file mode 100644 index 00000000000..526aa0d97aa --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/starter/IdempotencyCommandPropertyCheckAutoConfiguration.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.starter; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE; + +import org.apache.fineract.command.audit.AuditCommandProperties; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.context.annotation.ComponentScan; + +// note: deliberately not conditional on the idempotency properties; the check has to see the combination that would +// otherwise switch this module off, and it binds the audit properties itself so that it can read them while the audit +// module is disabled and its own auto-configuration has backed off +@AutoConfiguration +@EnableConfigurationProperties({ IdempotencyCommandProperties.class, AuditCommandProperties.class }) +@ComponentScan(COMMAND_IDEMPOTENCY_CHECK_BASE_PACKAGE) +public class IdempotencyCommandPropertyCheckAutoConfiguration {} diff --git a/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java new file mode 100644 index 00000000000..18dfa7b773c --- /dev/null +++ b/fineract-command-idempotency/src/main/java/org/apache/fineract/command/idempotency/web/IdempotencyCommandExceptionHandler.java @@ -0,0 +1,50 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; + +import lombok.extern.slf4j.Slf4j; +import org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.Order; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.ExceptionHandler; +import org.springframework.web.bind.annotation.RestControllerAdvice; + +/** + * The Spring MVC counterpart of {@link IdempotencyCommandExceptionMapper}. Endpoints built on the command framework + * exist on both web stacks, and a repeated request has to be answered the same way whichever one serves it. + *

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

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

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

+ * These are the same guarantees the old command processing gives, as pinned by + * {@code org.apache.fineract.integrationtests.IdempotencyTest}. + */ +@Slf4j +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +public class IdempotencyEndToEndTest extends CommandBaseTest { + + /** The distinctor of the {@code /sync} command under the default, {@code ENTITY_NAME_AND_ACTION_NAME}. */ + private static final String SYNC = "DUMMY|CREATE"; + + @LocalServerPort + private int port; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @org.springframework.beans.factory.annotation.Autowired + private CommandStore store; + + @org.springframework.beans.factory.annotation.Autowired + private JdbcCommandRepository repository; + + @Test + public void aRequestWithoutAKeyIsNeverTreatedAsARepeat() { + var first = post("/sync", "hello", null); + var second = post("/sync", "hello", null); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "A request without a key must be processed."); + assertTrue(second.getStatusCode().is2xxSuccessful(), "A second request without a key must be processed too."); + assertFalse(servedFromCache(second), "Nothing can be replayed without an idempotency key."); + } + + @Test + public void theFirstRequestIsProcessedAndTheRepeatIsReplayed() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + assertFalse(servedFromCache(first), "The first request is executed, not replayed."); + assertNotNull(first.getBody(), "The first request must return a body."); + + var second = post("/sync", "hello", key); + + assertTrue(servedFromCache(second), "A repeat must be marked as served from the command store."); + assertEquals(first.getStatusCode(), second.getStatusCode(), "A repeat must be answered with the original status."); + assertEquals(first.getBody(), second.getBody(), "A repeat must be answered with the original body."); + } + + @Test + public void aRepeatOfAFailedRequestFailsTheSameWay() { + var key = UUID.randomUUID().toString(); + + // this endpoint always fails, so the command is stored as failed + var first = post("/error", "boom", key); + + assertTrue(first.getStatusCode().is4xxClientError(), "The request must fail, got " + first.getStatusCode() + " " + first.getBody()); + assertFalse(servedFromCache(first), "The first failure is produced, not replayed."); + + var second = post("/error", "boom", key); + + assertTrue(servedFromCache(second), "A repeat of a failure must be marked as served from the command store."); + assertEquals(first.getStatusCode(), second.getStatusCode(), "A repeat must fail with the original status."); + assertEquals(first.getBody(), second.getBody(), "A repeat must fail with the original body."); + } + + @Test + public void aThirdRepeatIsAnsweredLikeTheSecond() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + var second = post("/sync", "hello", key); + var third = post("/sync", "hello", key); + + // the earlier implementation accumulated rows per repeat and broke on the third request + assertEquals(first.getStatusCode(), third.getStatusCode(), "Repeats must stay stable however often they are made."); + assertEquals(second.getBody(), third.getBody(), "Repeats must stay stable however often they are made."); + assertTrue(servedFromCache(third), "Every repeat is served from the command store."); + } + + @Test + public void aKeyReusedForADifferentRequestIsRejected() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + var different = post("/sync", "something-else", key); + + assertEquals(409, different.getStatusCode().value(), "Reusing a key for a different request must not replay the first answer."); + } + + @Test + public void concurrentRepeatsExecuteTheCommandOnlyOnce() throws Exception { + var threads = 6; + var key = UUID.randomUUID().toString(); + var startLine = new CountDownLatch(1); + var executed = new AtomicInteger(); + var replayed = new AtomicInteger(); + var tooEarly = new AtomicInteger(); + + try (var executor = Executors.newFixedThreadPool(threads)) { + var calls = IntStream.range(0, threads).mapToObj(i -> executor.submit(() -> { + startLine.await(); + + var response = post("/sync", "hello", key); + + if (servedFromCache(response)) { + replayed.incrementAndGet(); + } else if (response.getStatusCode().value() == 425) { + tooEarly.incrementAndGet(); + } else { + executed.incrementAndGet(); + } + + return null; + })).toList(); + + startLine.countDown(); + + for (var call : calls) { + call.get(60, TimeUnit.SECONDS); + } + } + + assertEquals(1, executed.get(), "Exactly one concurrent request may execute the command."); + assertEquals(threads - 1, replayed.get() + tooEarly.get(), "Every other request must be replayed or told it is too early."); + } + + @Test + public void aRequestForACommandStillRunningIsToldItIsTooEarly() { + var key = UUID.randomUUID().toString(); + var inFlight = new DummyCommand(); + + inFlight.setPayload(DummyRequest.builder().content("hello").build()); + inFlight.setIdempotencyKey(key); + // as the hook would have claimed it under the default distinctor + inFlight.setCustomIdempotencyDistinctor(SYNC); + inFlight.setCreatedAt(java.time.Instant.now()); + + // claim the key without ever completing it, which is what another node mid-request looks like + store.claim(inFlight); + + var response = post("/sync", "hello", key); + + assertEquals(425, response.getStatusCode().value(), "A command that has not finished must answer 425 Too Early."); + assertTrue(servedFromCache(response), "The answer comes from the command store, so it carries the replay header."); + } + + @Test + public void oneCommandIsRecordedAndRepeatsNeverAddAnother() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + var recorded = repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, SYNC).orElseThrow(); + + assertEquals(CommandState.PROCESSED, recorded.getState(), "A processed command must be audited as processed."); + assertNotNull(recorded.getResponse(), "The result the command produced must be recorded."); + assertNull(recorded.getResponseStatusCode(), "A command that produced a result needs no recorded status: its " + + "repeat is answered by handing that result back, and the web layer derives the status from it."); + + post("/sync", "hello", key); + post("/sync", "hello", key); + + assertEquals(1, + repository.findAll().stream() + .filter(e -> key.equals(e.getIdempotencyKey()) && SYNC.equals(e.getCustomIdempotencyDistinctor())).count(), + "Repeats must not add command records under the key and its distinctor."); + + var afterRepeats = repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, SYNC).orElseThrow(); + + assertEquals(CommandState.PROCESSED, afterRepeats.getState(), "A repeat must not change the recorded outcome."); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(org.springframework.http.MediaType.APPLICATION_JSON); + + if (idempotencyKey != null) { + headers.add("Idempotency-Key", idempotencyKey); + } + + var body = content == null ? DummyRequest.builder().build() : DummyRequest.builder().content(content).build(); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, new HttpEntity<>(body, headers), + String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst(IDEMPOTENT_CACHE_HEADER)); + } + + /** + * The failure cases are part of the contract under test, so an error status has to come back as a response rather + * than as an exception. + */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java new file mode 100644 index 00000000000..3b40e0fccc8 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyEntityAndActionScopeEndToEndTest.java @@ -0,0 +1,137 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.apache.fineract.command.core.exception.AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, under the default distinctor, {@code ENTITY_NAME_AND_ACTION_NAME}: + * the key is scoped to the command's entity and action, the way the legacy command processing scopes it. Nothing is + * configured here on purpose, so that this also pins which distinctor is the default. The sample commands are + * {@code DUMMY|CREATE} on {@code /sync} and {@code DUMMY|ERROR} on {@code /error}. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +public class IdempotencyEntityAndActionScopeEndToEndTest extends CommandBaseTest { + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void theSameKeyOnAnotherCommandIsExecutedAsANewCommand() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + var otherCommand = post("/error", "boom", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + assertTrue(otherCommand.getStatusCode().is4xxClientError(), + "Another entity and action under the same key is a new command, so it must run - and this one fails - " + + "rather than be refused as a conflict; got " + otherCommand.getStatusCode()); + assertFalse(servedFromCache(otherCommand), "It was executed, not replayed."); + + assertEquals(CommandState.PROCESSED, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "DUMMY|CREATE").orElseThrow().getState()); + assertEquals(CommandState.ERROR, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "DUMMY|ERROR").orElseThrow().getState()); + } + + @Test + public void aRepeatUnderTheSameEntityAndActionIsReplayed() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + post("/error", "boom", key); + + var repeat = post("/sync", "hello", key); + + assertTrue(servedFromCache(repeat), "A repeat under the same entity and action must be replayed."); + assertEquals(first.getStatusCode(), repeat.getStatusCode()); + assertEquals(first.getBody(), repeat.getBody(), "It must be answered from its own row, not the other command's."); + } + + @Test + public void aRepeatOfTheFailedCommandIsAnsweredWithItsOwnFailure() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + var failure = post("/error", "boom", key); + var repeat = post("/error", "boom", key); + + assertTrue(servedFromCache(repeat), "A repeat of the failed command must be replayed."); + assertEquals(failure.getStatusCode(), repeat.getStatusCode(), + "The status recorded for the failed command must be found under its own distinctor."); + assertEquals(failure.getBody(), repeat.getBody()); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content(content).build(), headers), String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst(IDEMPOTENT_CACHE_HEADER)); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java new file mode 100644 index 00000000000..55c5e2b99f6 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyNoDistinctorEndToEndTest.java @@ -0,0 +1,110 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.test.context.TestPropertySource; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, with {@code NONE}: nothing distinguishes a key, so it identifies + * one command for the whole tenant - stricter than the legacy command processing, which scopes a key by entity and + * action. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = TestConfiguration.class) +@TestPropertySource(properties = "fineract.command.idempotency.custom-distinctor=NONE") +public class IdempotencyNoDistinctorEndToEndTest extends CommandBaseTest { + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void aKeyIsUniqueAcrossCommandsNotOnlyWithinOne() { + var key = UUID.randomUUID().toString(); + + var first = post("/sync", "hello", key); + + assertTrue(first.getStatusCode().is2xxSuccessful(), "The first request must be processed."); + + var otherCommand = post("/error", "boom", key); + + assertEquals(409, otherCommand.getStatusCode().value(), + "Reusing a key for a different command must be rejected, not executed and not replayed."); + } + + @Test + public void theKeyIsStoredWithTheEmptyDistinctor() { + var key = UUID.randomUUID().toString(); + + post("/sync", "hello", key); + + assertEquals(CommandState.PROCESSED, + repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, "").orElseThrow().getState(), + "Under NONE the key is claimed with the empty distinctor."); + } + + private ResponseEntity post(String path, String content, String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy" + path, HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content(content).build(), headers), String.class); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java new file mode 100644 index 00000000000..d81d5b42a42 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/IdempotencyRecoverableErrorEndToEndTest.java @@ -0,0 +1,139 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT; + +import java.util.UUID; +import org.apache.fineract.command.core.CommandState; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.apache.fineract.command.jdbc.store.domain.CommandEntity; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.test.CommandBaseTest; +import org.apache.fineract.command.test.sample.data.DummyRequest; +import org.apache.fineract.command.test.sample.exception.DummyException; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.web.server.LocalServerPort; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.http.HttpEntity; +import org.springframework.http.HttpHeaders; +import org.springframework.http.HttpMethod; +import org.springframework.http.MediaType; +import org.springframework.http.ResponseEntity; +import org.springframework.test.context.ContextConfiguration; +import org.springframework.web.client.RestTemplate; + +/** + * The same chain as {@link IdempotencyEndToEndTest}, with the sample command's failure classified as recoverable: a + * retry under the same key has to be executed again rather than answered with the stored failure, and the failure has + * to stay on record. + */ +@SpringBootTest(webEnvironment = RANDOM_PORT) +@ContextConfiguration(classes = { TestConfiguration.class, IdempotencyRecoverableErrorEndToEndTest.RecoverableDummyFailures.class }) +public class IdempotencyRecoverableErrorEndToEndTest extends CommandBaseTest { + + /** The distinctor of the {@code /error} command under the default, {@code ENTITY_NAME_AND_ACTION_NAME}. */ + private static final String ERROR = "DUMMY|ERROR"; + + @LocalServerPort + private int port; + + @Autowired + private JdbcCommandRepository repository; + + private final RestTemplate restTemplate = errorTolerantRestTemplate(); + + @Test + public void aRetryAfterARecoverableFailureIsExecutedAgain() { + var key = UUID.randomUUID().toString(); + + var first = post(key); + var retry = post(key); + + assertTrue(first.getStatusCode().is4xxClientError(), "The command must fail, got " + first.getStatusCode()); + assertFalse(servedFromCache(retry), "A retry after a recoverable failure must be executed, not answered from the store."); + assertEquals(first.getStatusCode(), retry.getStatusCode(), "Executed again, it fails again the same way."); + } + + @Test + public void theFailureStaysOnRecordUnderTheMovedKey() { + var key = UUID.randomUUID().toString(); + + post(key); + + assertTrue(repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, ERROR).isEmpty(), + "The original key must be free for the retry."); + + var moved = repository.findAll().stream().filter(row -> row.getIdempotencyKey().startsWith(key + "_RE")).toList(); + + assertEquals(1, moved.size(), "The failed command must still be recorded, under its moved key."); + + CommandEntity row = moved.get(0); + + assertEquals(key + "_RE" + row.getId(), row.getIdempotencyKey()); + assertEquals(CommandState.ERROR, row.getState()); + assertEquals(ERROR, row.getCustomIdempotencyDistinctor()); + assertNotNull(row.getResponseStatusCode(), "The answer the client was sent must be recorded against the moved row."); + } + + private ResponseEntity post(String idempotencyKey) { + var headers = new HttpHeaders(); + + headers.setContentType(MediaType.APPLICATION_JSON); + headers.add("Idempotency-Key", idempotencyKey); + + return restTemplate.exchange("http://localhost:" + port + "/test/dummy/error", HttpMethod.POST, + new HttpEntity<>(DummyRequest.builder().content("boom").build(), headers), String.class); + } + + private static boolean servedFromCache(ResponseEntity response) { + return "true".equals(response.getHeaders().getFirst("x-served-from-cache")); + } + + /** Error statuses are part of what is under test, so they have to come back as responses, not exceptions. */ + private static RestTemplate errorTolerantRestTemplate() { + var template = new RestTemplate(); + + template.setErrorHandler(new org.springframework.web.client.ResponseErrorHandler() { + + @Override + public boolean hasError(org.springframework.http.client.ClientHttpResponse response) { + return false; + } + }); + + return template; + } + + @Configuration + static class RecoverableDummyFailures { + + @Bean + RecoverableCommandErrorClassifier recoverableCommandErrorClassifier() { + return error -> error instanceof DummyException; + } + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java new file mode 100644 index 00000000000..986b893d5d6 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/RecoverableErrorKeyTest.java @@ -0,0 +1,49 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.junit.jupiter.api.Test; + +class RecoverableErrorKeyTest { + + @Test + void aKeyThatFitsKeepsItsTextAndGainsTheRowId() { + assertThat(RecoverableErrorKey.movedKey("idk", 42)).isEqualTo("idk_RE42"); + } + + @Test + void aKeyThatWouldNotFitIsHashedSoThatTheMovedKeyAlwaysFits() { + var longKey = "k".repeat(RecoverableErrorKey.KEY_LENGTH); + var moved = RecoverableErrorKey.movedKey(longKey, Long.MAX_VALUE); + + assertThat(moved).hasSizeLessThanOrEqualTo(RecoverableErrorKey.KEY_LENGTH).endsWith("_RE" + Long.MAX_VALUE) + .matches("[0-9a-f]{" + RecoverableErrorKey.HASH_LENGTH + "}_RE[0-9]+"); + assertThat(RecoverableErrorKey.movedKey(longKey, Long.MAX_VALUE)).as("The same key must always move to the same place.") + .isEqualTo(moved); + } + + @Test + void theLongestKeyThatFitsIsNotHashed() { + var key = "k".repeat(RecoverableErrorKey.KEY_LENGTH - "_RE7".length()); + + assertThat(RecoverableErrorKey.movedKey(key, 7)).isEqualTo(key + "_RE7"); + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java new file mode 100644 index 00000000000..29b423e0113 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/TestConfiguration.java @@ -0,0 +1,38 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.boot.autoconfigure.EnableAutoConfiguration; +import org.springframework.context.annotation.ComponentScan; +import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.PropertySource; +import org.springframework.data.jdbc.repository.config.EnableJdbcRepositories; + +/** + * Wires the whole chain the way a real deployment does: the sample API, the command framework, the audit hooks, the + * JDBC store and this module. Only then does an end-to-end test say anything about how a repeated request is answered. + */ +@Slf4j +@Configuration +@EnableAutoConfiguration +@EnableJdbcRepositories(basePackages = { "org.apache.fineract.command.jdbc.store.domain" }) +@PropertySource("classpath:application-test.properties") +@ComponentScan({ "org.apache.fineract.command.jdbc.store", "org.apache.fineract.command.test.sample" }) +public class TestConfiguration {} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java new file mode 100644 index 00000000000..70b1c38f032 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/check/IdempotencyCommandPropertyCheckTest.java @@ -0,0 +1,116 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.check; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.apache.fineract.command.idempotency.starter.IdempotencyCommandPropertyCheckAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * Covers the ways idempotency and auditing can be configured against each other. + * + *

+ * The mistakes are the ones that would otherwise go unnoticed: idempotency on with auditing off, or with the audit hook + * that records a completed or a failed command off. Nothing fails at startup, the first request for a key is answered + * normally, and the breakage shows up only when a client retries - as a 425 that does not resolve. The point of the + * check is to turn that into a startup failure. + */ +class IdempotencyCommandPropertyCheckTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(IdempotencyCommandPropertyCheckAutoConfiguration.class)); + + @Test + void bothOnIsTheDefaultAndStarts() { + contextRunner.run(context -> assertThat(context) + .as("Idempotency and auditing are both on unless switched off, which is the supported arrangement.").hasNotFailed()); + } + + @Test + void auditingOnItsOwnStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false").run(context -> assertThat(context) + .as("Auditing without idempotency is fine: commands are recorded, no key is read, nothing is replayed.").hasNotFailed()); + } + + @Test + void idempotencyWithoutAuditingRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.enabled=false").run(context -> assertThat(context) + .as("A claimed key would never leave UNDER_PROCESSING, so every repeat would answer 425 for ever.").hasFailed().getFailure() + .rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("fineract.command.audit.enabled")); + } + + @Test + void idempotencyWithoutTheAfterHookRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.hook-post-enabled=false").run(context -> assertThat(context) + .as("Nothing would record a completed command, so its repeats would be told it never finished.").hasFailed().getFailure() + .rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("fineract.command.audit.hook-post-enabled")); + } + + @Test + void idempotencyWithoutTheErrorHookRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.audit.hook-error-enabled=false") + .run(context -> assertThat(context) + .as("Nothing would record a failed command, so its repeats would never be answered with the failure.").hasFailed() + .getFailure().rootCause().isInstanceOf(IllegalStateException.class) + .hasMessageContaining("fineract.command.audit.hook-error-enabled")); + } + + @Test + void idempotencyWithoutTheBeforeHookStarts() { + contextRunner.withPropertyValues("fineract.command.audit.hook-pre-enabled=false").run( + context -> assertThat(context).as("Claiming the key already writes the row the before hook would write.").hasNotFailed()); + } + + @Test + void auditHooksOffWithoutIdempotencyStarts() { + contextRunner + .withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.hook-post-enabled=false", + "fineract.command.audit.hook-error-enabled=false") + .run(context -> assertThat(context).as("Without idempotency nothing depends on the hooks.").hasNotFailed()); + } + + @Test + void aClaimTimeoutOfZeroSwitchesTheTimeoutOffAndStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=0").run(context -> assertThat(context) + .as("Zero is how the timeout is switched off, which is the legacy behaviour.").hasNotFailed()); + } + + @Test + void anEmptyClaimTimeoutSwitchesTheTimeoutOffAndStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=").run(context -> assertThat(context) + .as("An empty value, as an unset environment variable gives, is the same as zero.").hasNotFailed()); + } + + @Test + void aNegativeClaimTimeoutRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.idempotency.claim-timeout=-1m") + .run(context -> assertThat(context) + .as("A negative age is always exceeded, so even a running command would be declared abandoned.").hasFailed() + .getFailure().rootCause().isInstanceOf(IllegalStateException.class).hasMessageContaining("claim-timeout")); + } + + @Test + void bothOffStarts() { + contextRunner.withPropertyValues("fineract.command.idempotency.enabled=false", "fineract.command.audit.enabled=false").run( + context -> assertThat(context).as("Neither feature is on, so nothing is written to the command table.").hasNotFailed()); + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java new file mode 100644 index 00000000000..2f6c9021bb0 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/distinctor/CustomIdempotencyDistinctorTest.java @@ -0,0 +1,97 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.distinctor; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; + +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.idempotency.starter.IdempotencyCommandAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * Pins what each distinctor returns and which one {@code fineract.command.idempotency.custom-distinctor} selects. + */ +class CustomIdempotencyDistinctorTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(IdempotencyCommandAutoConfiguration.class)) + .withBean(CommandStore.class, () -> mock(CommandStore.class)); + + @Test + void noneDistinguishesNothing() { + assertThat(new NoCustomIdempotencyDistinctor().distinctorFor(command("LOAN", "CREATE"))).isEmpty(); + } + + @Test + void entityAndActionNameJoinsTheEntityAndTheActionWithABar() { + assertThat(new EntityAndActionNameCustomIdempotencyDistinctor().distinctorFor(command("LOAN", "CREATE"))).isEqualTo("LOAN|CREATE"); + } + + @Test + void entityNameAndActionNameIsSelectedWhenNothingIsConfigured() { + contextRunner.run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class) + .isInstanceOf(EntityAndActionNameCustomIdempotencyDistinctor.class)); + } + + @Test + void noneSelectsNone() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=NONE").run(context -> assertThat(context) + .getBean(CustomIdempotencyDistinctor.class).isInstanceOf(NoCustomIdempotencyDistinctor.class)); + } + + @Test + void entityNameAndActionNameSelectsEntityAndActionName() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=ENTITY_NAME_AND_ACTION_NAME") + .run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class) + .isInstanceOf(EntityAndActionNameCustomIdempotencyDistinctor.class)); + } + + @Test + void anUnknownValueRefusesToStart() { + contextRunner.withPropertyValues("fineract.command.idempotency.custom-distinctor=ENTITY_ONLY") + .run(context -> assertThat(context).as("A typo must not silently fall back to another scope.").hasFailed()); + } + + @Test + void aDistinctorTheApplicationDefinesReplacesTheConfiguredOne() { + CustomIdempotencyDistinctor own = command -> "own"; + + contextRunner.withBean(CustomIdempotencyDistinctor.class, () -> own) + .run(context -> assertThat(context).getBean(CustomIdempotencyDistinctor.class).isSameAs(own)); + } + + private static Command command(String entity, String action) { + return new Command<>() { + + @Override + public String entityName() { + return entity; + } + + @Override + public String actionName() { + return action; + } + }; + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java new file mode 100644 index 00000000000..15c06087a44 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyCheckCommandHookTest.java @@ -0,0 +1,322 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.core.CommandState.ERROR; +import static org.apache.fineract.command.core.CommandState.PROCESSED; +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; +import static org.apache.fineract.command.core.CommandState.UNKNOWN; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import java.time.Duration; +import java.time.Instant; +import java.util.Map; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandReplay; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.exception.CommandIdempotencyConflictException; +import org.apache.fineract.command.core.exception.CommandIdempotencyFailedException; +import org.apache.fineract.command.core.exception.CommandIdempotencyInProgressException; +import org.apache.fineract.command.core.exception.CommandIdempotencyProcessedException; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.apache.fineract.command.idempotency.distinctor.CustomIdempotencyDistinctor; +import org.apache.fineract.command.idempotency.distinctor.EntityAndActionNameCustomIdempotencyDistinctor; +import org.apache.fineract.command.idempotency.distinctor.NoCustomIdempotencyDistinctor; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; + +@ExtendWith(MockitoExtension.class) +class IdempotencyCheckCommandHookTest { + + private static final String KEY = "7f3a1c04-0000-0000-0000-000000000000"; + + @Mock + private CommandStore store; + + private IdempotencyCheckCommandHook hook; + + @BeforeEach + void setUp() { + hook = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build(), new NoCustomIdempotencyDistinctor()); + } + + @Test + void aCommandWithoutAKeyIsNeverClaimed() { + var ctx = context(null); + + hook.onBefore(ctx); + + verifyNoInteractions(store); + assertFalse(ctx.isSkipExecution(), "A command without an idempotency key must be executed."); + } + + @Test + void winningTheClaimLetsTheCommandExecute() { + var ctx = context(KEY); + + when(store.claim(any())).thenReturn(true); + + hook.onBefore(ctx); + + assertFalse(ctx.isSkipExecution(), "The request that claims the key must be executed."); + verify(store, never()).getReplayByKey(anyString(), anyString()); + } + + @Test + void anUnfinishedCommandAnswersTooEarly() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now())); + + var exception = assertThrows(CommandIdempotencyInProgressException.class, () -> hook.onBefore(ctx)); + + assertEquals(425, exception.getStatusCode(), "An unfinished command must answer 425 Too Early."); + assertTrue(ctx.isSkipExecution(), "An in-flight command must not be executed a second time."); + // the request is not compared here: there is nothing stored to compare a response against yet + verify(store, never()).matchesStoredRequest(anyString(), anyString(), any()); + } + + @Test + void aProcessedCommandIsReplayedByHandingBackItsOwnResult() { + var ctx = context(KEY); + + var stored = Map.of("resourceId", 7); + + duplicate(new CommandReplay(PROCESSED, null, stored, Instant.now())); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); + + hook.onBefore(ctx); + + // nothing is thrown: the dispatcher returns this to the resource, which returns it as it returned the + // original, so the web layer renders the status and the bytes exactly as it did the first time + assertSame(stored, ctx.getResponse(), "A repeat is answered with the command's own stored result."); + assertTrue(ctx.isSkipExecution(), "A duplicate command must not be executed again."); + } + + @Test + void aProcessedCommandWithOnlyACapturedAnswerIsThrownWithItsRecordedStatus() { + var ctx = context(KEY); + + // no result object to hand back, so the answer captured as it went out is replayed as the text it is, and + // the status has to come from the record because nothing else can derive it + duplicate(new CommandReplay(PROCESSED, 201, "{\"resourceId\":7}", Instant.now())); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); + + var exception = assertThrows(CommandIdempotencyProcessedException.class, () -> hook.onBefore(ctx)); + + assertEquals(201, exception.getStatusCode(), "A replay must answer with the original status."); + assertEquals("{\"resourceId\":7}", exception.getResponse()); + } + + @Test + void aFailedCommandIsReplayedAsTheSameFailure() { + var ctx = context(KEY); + + var stored = Map.of("error", "bad request"); + + duplicate(new CommandReplay(ERROR, 400, stored, Instant.now())); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); + + // this is what the old processing does: a repeat of a failure fails identically rather than being retried + var exception = assertThrows(CommandIdempotencyFailedException.class, () -> hook.onBefore(ctx)); + + assertEquals(400, exception.getStatusCode(), "A repeat of a failed command must fail with the original status."); + assertSame(stored, exception.getResponse(), "A repeat of a failed command must return what was stored for it."); + assertTrue(ctx.isSkipExecution(), "A failed command must not be executed again by a repeat."); + } + + @Test + void aKeyReusedForADifferentRequestConflicts() { + var ctx = context(KEY); + + duplicate(new CommandReplay(PROCESSED, 200, Map.of(), Instant.now())); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(false); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), "Reusing a key for a different request is a conflict, not a replay."); + } + + @Test + void anUnrecognisedStateConflictsRatherThanGuessing() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNKNOWN, null, null, Instant.now())); + when(store.matchesStoredRequest(KEY, "", "request-payload")).thenReturn(true); + + assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + } + + @Test + void aStoredResultThatCannotBeReconstructedIsRefusedRatherThanGuessedAt() { + var ctx = context(KEY); + + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY, "")).thenThrow(new IllegalStateException("Cannot rehydrate a stored command result")); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), + "The key has been used and its answer cannot be produced, which is neither a success nor a failure of this request."); + assertTrue(String.valueOf(exception.getResponse()).contains("cannot be reconstructed"), + "The answer must say what went wrong rather than coming back empty."); + assertTrue(String.valueOf(exception.getResponse()).contains("was carried out"), + "Only a completed command stores a result, so the answer must say the command took effect."); + assertTrue(String.valueOf(exception.getResponse()).contains("Do not send it again"), + "Inviting a retry under a new key would execute a command that already took effect a second time."); + } + + @Test + void aClaimThatNeverFinishedIsRefusedRatherThanAskedToRetryForEver() { + var ctx = context(KEY); + + // claimed well past the timeout and still recorded as running: the command that claimed it never came back + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofHours(1)))); + + var exception = assertThrows(CommandIdempotencyConflictException.class, () -> hook.onBefore(ctx)); + + assertEquals(409, exception.getStatusCode(), + "425 would tell the caller to come back, and nothing will ever change, so they would retry for ever."); + assertTrue(String.valueOf(exception.getResponse()).contains("never finished"), + "The answer has to say why the key is unusable, or a caller cannot tell it from a transient 409."); + } + + @Test + void aClaimThatIsStillWithinItsTimeIsToldToComeBack() { + var ctx = context(KEY); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofMinutes(1)))); + + assertThrows(CommandIdempotencyInProgressException.class, () -> hook.onBefore(ctx), + "A command that could still be running must not be declared dead."); + } + + @Test + void withTheTimeoutSwitchedOffAnUnfinishedClaimIsToldToComeBackHoweverOld() { + for (var timeout : new Duration[] { Duration.ZERO, null }) { + var legacy = new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().claimTimeout(timeout).build(), + new NoCustomIdempotencyDistinctor()); + + duplicate(new CommandReplay(UNDER_PROCESSING, null, null, Instant.now().minus(Duration.ofDays(30)))); + + assertThrows(CommandIdempotencyInProgressException.class, () -> legacy.onBefore(context(KEY)), + "With no timeout (" + timeout + ") a claim is never declared abandoned, as in the legacy processing."); + } + } + + private void duplicate(CommandReplay replay) { + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY, "")).thenReturn(replay); + } + + @Test + void theDistinctorIsOnTheCommandBeforeItsKeyIsClaimed() { + var scoped = hookWith(new EntityAndActionNameCustomIdempotencyDistinctor()); + var ctx = context(KEY); + + when(store.claim(any())).thenAnswer(invocation -> { + assertEquals("DOCUMENT|CREATE", invocation.>getArgument(0).getCustomIdempotencyDistinctor(), + "The key is unique together with the distinctor, so the claim has to carry it."); + + return true; + }); + + scoped.onBefore(ctx); + + assertEquals("DOCUMENT|CREATE", ctx.getCommand().getCustomIdempotencyDistinctor()); + assertFalse(ctx.isSkipExecution(), "A command that claimed its key must be executed."); + } + + @Test + void aRepeatIsLookedUpUnderItsOwnDistinctor() { + var scoped = hookWith(new EntityAndActionNameCustomIdempotencyDistinctor()); + var ctx = context(KEY); + var replay = new CommandReplay(ERROR, 400, "{\"error\":\"bad request\"}", Instant.now()); + + when(store.claim(any())).thenReturn(false); + when(store.getReplayByKey(KEY, "DOCUMENT|CREATE")).thenReturn(replay); + when(store.matchesStoredRequest(KEY, "DOCUMENT|CREATE", "request-payload")).thenReturn(true); + + var exception = assertThrows(CommandIdempotencyFailedException.class, () -> scoped.onBefore(ctx)); + + assertEquals(400, exception.getStatusCode(), "The repeat must be answered from the row with the same key and distinctor."); + } + + @Test + void aDistinctorThatReturnsNothingIsRefusedBeforeTheKeyIsClaimed() { + var broken = hookWith(command -> null); + + var exception = assertThrows(IllegalStateException.class, () -> broken.onBefore(context(KEY))); + + assertTrue(exception.getMessage().contains("empty string"), "The message must say what to return instead."); + verifyNoInteractions(store); + } + + @Test + void aDistinctorTooLongForItsColumnIsRefusedBeforeTheKeyIsClaimed() { + var broken = hookWith(command -> "x".repeat(CustomIdempotencyDistinctor.MAX_LENGTH + 1)); + + var exception = assertThrows(IllegalStateException.class, () -> broken.onBefore(context(KEY))); + + assertTrue(exception.getMessage().contains(String.valueOf(CustomIdempotencyDistinctor.MAX_LENGTH)), + "The message must name the limit."); + verifyNoInteractions(store); + } + + private IdempotencyCheckCommandHook hookWith(CustomIdempotencyDistinctor distinctor) { + return new IdempotencyCheckCommandHook(store, IdempotencyCommandProperties.builder().build(), distinctor); + } + + private static CommandContext context(String key) { + var command = new TestCommand(); + + command.setIdempotencyKey(key); + command.setPayload("request-payload"); + + return CommandContext.builder().command(command).build(); + } + + /** Commands declare their names in code; a test fixture has to as well. */ + private static final class TestCommand extends Command { + + @Override + public String entityName() { + return "DOCUMENT"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java new file mode 100644 index 00000000000..2647098d9da --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/hook/IdempotencyRecoverableErrorCommandHookTest.java @@ -0,0 +1,156 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.hook; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import java.util.concurrent.CompletionException; +import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.web.context.request.RequestContextHolder; +import org.springframework.web.context.request.ServletRequestAttributes; + +class IdempotencyRecoverableErrorCommandHookTest { + + private static final String KEY = "idk"; + + private static final long COMMAND_ID = 42L; + + private final CommandStore store = mock(CommandStore.class); + + private final MockHttpServletRequest request = new MockHttpServletRequest(); + + @BeforeEach + void bindRequest() { + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, KEY); + RequestContextHolder.setRequestAttributes(new ServletRequestAttributes(request)); + } + + @AfterEach + void unbindRequest() { + RequestContextHolder.resetRequestAttributes(); + } + + @Test + void aRecoverableFailureReleasesTheKey() { + var ctx = failed(new IllegalStateException("try again")); + + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).as("The failure moves aside, so the audit hook stores it there.") + .isEqualTo("idk_RE42"); + assertThat(request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE)) + .as("The answer the client is sent has to be recorded against the moved row.").isEqualTo("idk_RE42"); + verify(store).existsByKey("idk_RE42", "LOAN|CREATE"); + } + + @Test + void anyOtherFailureKeepsTheKey() { + var ctx = failed(new IllegalStateException("no")); + + hook(error -> false).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + assertThat(request.getAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE)).isEqualTo(KEY); + } + + @Test + void aRefusedRepeatReleasesNothing() { + var ctx = failed(new IllegalStateException("try again")); + + ctx.setSkipExecution(true); + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).as("A repeat never claimed the key, so it is not its to release.").isEqualTo(KEY); + verifyNoInteractions(store); + } + + @Test + void aMovedKeyThatIsAlreadyTakenKeepsTheFailureUnderTheOriginalKey() { + var ctx = failed(new IllegalStateException("try again")); + + when(store.existsByKey(anyString(), anyString())).thenReturn(true); + hook(error -> true).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + } + + @Test + void aClassifierThatFailsKeepsTheKeyAndLetsTheOriginalErrorThrough() { + var ctx = failed(new IllegalStateException("try again")); + + hook(error -> { + throw new IllegalArgumentException("the configuration could not be read"); + }).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo(KEY); + } + + @Test + void aFailureHandedBackWrappedIsClassifiedByWhatItWraps() { + var ctx = failed(new CompletionException(new UnsupportedOperationException("try again"))); + + hook(error -> error instanceof UnsupportedOperationException).onError(ctx); + + assertThat(ctx.getCommand().getIdempotencyKey()).isEqualTo("idk_RE42"); + } + + private IdempotencyRecoverableErrorCommandHook hook(RecoverableCommandErrorClassifier classifier) { + return new IdempotencyRecoverableErrorCommandHook(store, classifier); + } + + private static CommandContext failed(Throwable error) { + var command = new TestCommand(); + + command.setIdempotencyKey(KEY); + command.setCustomIdempotencyDistinctor("LOAN|CREATE"); + command.setCommandId(COMMAND_ID); + + var ctx = CommandContext.builder().command(command).build(); + + ctx.setError(error); + + return ctx; + } + + private static final class TestCommand extends Command { + + @Override + public String entityName() { + return "LOAN"; + } + + @Override + public String actionName() { + return "CREATE"; + } + } +} diff --git a/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java new file mode 100644 index 00000000000..f95295325b4 --- /dev/null +++ b/fineract-command-idempotency/src/test/java/org/apache/fineract/command/idempotency/web/IdempotencyResponseCaptureFilterTest.java @@ -0,0 +1,160 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.idempotency.web; + +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE; +import static org.apache.fineract.command.idempotency.IdempotencyCommandConstants.COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.ArgumentMatchers.isNull; +import static org.mockito.Mockito.doThrow; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.idempotency.IdempotencyCommandProperties; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; +import org.springframework.mock.web.MockFilterChain; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.mock.web.MockHttpServletResponse; + +/** + * Covers what the filter does with an answer it cannot store. + * + *

+ * The response column holds JSON and nothing else, so an answer of any other kind is dropped and the repeat of that key + * is left with a status and an empty body. That is worth a log line, but only the shape of the answer: a response on + * this API can carry customer data, and keeping that out of the logs is the concern the masking elsewhere answers. + */ +class IdempotencyResponseCaptureFilterTest { + + private static final String KEY = "a-key"; + + private final CommandStore store = mock(CommandStore.class); + + private final IdempotencyResponseCaptureFilter filter = new IdempotencyResponseCaptureFilter(store, + IdempotencyCommandProperties.builder().build()); + + private final ListAppender captured = new ListAppender<>(); + + private Logger logger; + + @BeforeEach + void captureLogging() { + // by name rather than by class: this is deliberately another class's logger, which is what the appender + // has to attach to in order to read what the filter logged + logger = (Logger) LoggerFactory.getLogger(IdempotencyResponseCaptureFilter.class.getName()); + + captured.start(); + logger.addAppender(captured); + } + + @AfterEach + void stopCapturingLogging() { + logger.detachAppender(captured); + } + + @Test + void anAnswerThatIsNotJsonIsReportedWithoutItsBody() throws Exception { + var csv = "id,amount\n7,1.50\n"; + var response = runWith("text/csv", csv); + + verify(store).recordResponse(eq(KEY), eq(""), eq(200), isNull()); + + assertFalse(logged().contains("id,amount"), "The body must not reach the log: responses here carry customer data."); + assertTrue( + logged().contains(KEY) && logged().contains("text/csv") + && logged().contains(csv.getBytes(java.nio.charset.StandardCharsets.UTF_8).length + " bytes"), + "What is logged is the shape of the answer - key, status, content type and size - so the loss is " + + "diagnosable without copying the answer into the log."); + assertEquals(csv, response.getContentAsString(), "Whatever the filter does with its copy, the client still receives the answer."); + } + + @Test + void anAnswerThatCannotBeRecordedIsReportedWithoutItsBody() throws Exception { + doThrow(new IllegalStateException("the database is unavailable")).when(store).recordResponse(eq(KEY), eq(""), eq(200), + eq("{\"amount\":1.50}")); + + runWith("application/json", "{\"amount\":1.50}"); + + assertFalse(logged().contains("{\"amount\":1.50}"), "The body must not reach the log, even when recording it failed."); + assertTrue(logged().contains(KEY) && logged().contains("application/json"), + "A record that could not be written leaves the key unanswerable, which has to be loud - but it is the " + + "failure that is logged, not the answer."); + } + + @Test + void aJsonAnswerIsRecordedRatherThanLogged() throws Exception { + runWith("application/json", "{\"amount\":1.50}"); + + verify(store).recordResponse(KEY, "", 200, "{\"amount\":1.50}"); + + assertTrue(logged().isEmpty(), "Nothing is lost on the ordinary path, so nothing is logged about it."); + } + + @Test + void theAnswerIsRecordedAgainstTheDistinctorTheKeyWasClaimedWith() throws Exception { + runWith("application/json", "{\"amount\":1.50}", "PAYMENTTYPE|CREATE"); + + verify(store).recordResponse(KEY, "PAYMENTTYPE|CREATE", 200, "{\"amount\":1.50}"); + } + + private MockHttpServletResponse runWith(String contentType, String body) throws Exception { + return runWith(contentType, body, null); + } + + private MockHttpServletResponse runWith(String contentType, String body, String distinctor) throws Exception { + var request = new MockHttpServletRequest("POST", "/commands"); + + request.addHeader(IdempotencyCommandProperties.builder().build().getKeyHeaderName(), KEY); + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_KEY_ATTRIBUTE, KEY); + + if (distinctor != null) { + request.setAttribute(COMMAND_IDEMPOTENCY_CLAIMED_DISTINCTOR_ATTRIBUTE, distinctor); + } + + var response = new MockHttpServletResponse(); + var chain = new MockFilterChain() { + + @Override + public void doFilter(jakarta.servlet.ServletRequest req, jakarta.servlet.ServletResponse res) throws java.io.IOException { + res.setContentType(contentType); + res.getWriter().write(body); + } + }; + + filter.doFilter(request, response, chain); + + return response; + } + + private String logged() { + return captured.list.stream().filter(event -> event.getLevel().isGreaterOrEqual(Level.WARN)).map(ILoggingEvent::getFormattedMessage) + .reduce("", String::concat); + } +} diff --git a/fineract-command-idempotency/src/test/resources/application-test.properties b/fineract-command-idempotency/src/test/resources/application-test.properties new file mode 100644 index 00000000000..d35f0d3bb32 --- /dev/null +++ b/fineract-command-idempotency/src/test/resources/application-test.properties @@ -0,0 +1,45 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +fineract.command.enabled=true +fineract.command.hook-servlet-headers-enabled=true +fineract.command.hook-timestamp-enabled=true +fineract.command.hook-username-enabled=true + +fineract.command.jdbc.enabled=true +fineract.command.jdbc.file-dead-letter-queue-enabled=false +fineract.command.jdbc.file-dead-letter-queue-path=./build/fineract/dlq + +fineract.command.audit.enabled=true +fineract.command.audit.hook-pre-enabled=true +fineract.command.audit.hook-post-enabled=true +fineract.command.audit.hook-error-enabled=true + +fineract.command.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true + +spring.liquibase.enabled=true +spring.liquibase.drop-first=true +spring.liquibase.default-schema=public +spring.liquibase.change-log=classpath:/db/changelog/tenant/module/command/module-changelog-master.xml + +# the sample API renders errors through a MessageSource, same as the real application does +spring.messages.basename=org/apache/fineract/messages diff --git a/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties b/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties new file mode 100644 index 00000000000..eb14d22f2db --- /dev/null +++ b/fineract-command-idempotency/src/test/resources/org/apache/fineract/messages.properties @@ -0,0 +1,71 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# common +org.apache.fineract.common.validation.error=Validation Error +org.apache.fineract.common.validation.AssertFalse.message=must be false +org.apache.fineract.common.validation.AssertTrue.message=must be true +org.apache.fineract.common.validation.DecimalMax.message=must be less than ${inclusive == true ? 'or equal to ' : ''}{value} +org.apache.fineract.common.validation.DecimalMin.message=must be greater than ${inclusive == true ? 'or equal to ' : ''}{value} +org.apache.fineract.common.validation.Digits.message=numeric value out of bounds (<{integer} digits>.<{fraction} digits> expected) +org.apache.fineract.common.validation.Email.message=must be a well-formed email address +org.apache.fineract.common.validation.Future.message=must be a future date +org.apache.fineract.common.validation.FutureOrPresent.message=must be a date in the present or in the future +org.apache.fineract.common.validation.Max.message=must be less than or equal to {value} +org.apache.fineract.common.validation.Min.message=must be greater than or equal to {value} +org.apache.fineract.common.validation.Negative.message=must be less than 0 +org.apache.fineract.common.validation.NegativeOrZero.message=must be less than or equal to 0 +org.apache.fineract.common.validation.NotBlank.message=must not be blank +org.apache.fineract.common.validation.NotEmpty.message=must not be empty +org.apache.fineract.common.validation.NotNull.message=must not be null +org.apache.fineract.common.validation.Null.message=must be null +org.apache.fineract.common.validation.Past.message=must be a past date +org.apache.fineract.common.validation.PastOrPresent.message=must be a date in the past or in the present +org.apache.fineract.common.validation.Pattern.message=must match "{regexp}" +org.apache.fineract.common.validation.Positive.message=must be greater than 0 +org.apache.fineract.common.validation.PositiveOrZero.message=must be greater than or equal to 0 +org.apache.fineract.common.validation.Size.message=size must be between {min} and {max} +org.apache.fineract.common.validation.CreditCardNumber.message=invalid credit card number +org.apache.fineract.common.validation.Currency.message=invalid currency (must be one of {value}) +org.apache.fineract.common.validation.EAN.message=invalid {type} barcode +org.apache.fineract.common.validation.ISBN.message=invalid ISBN +org.apache.fineract.common.validation.Length.message=length must be between {min} and {max} +org.apache.fineract.common.validation.CodePointLength.message=length must be between {min} and {max} +org.apache.fineract.common.validation.LuhnCheck.message=the check digit for ${validatedValue} is invalid, Luhn Modulo 10 checksum failed +org.apache.fineract.common.validation.Mod10Check.message=the check digit for ${validatedValue} is invalid, Modulo 10 checksum failed +org.apache.fineract.common.validation.Mod11Check.message=the check digit for ${validatedValue} is invalid, Modulo 11 checksum failed +org.apache.fineract.common.validation.ModCheck.message=the check digit for ${validatedValue} is invalid, {modType} checksum failed +org.apache.fineract.common.validation.Normalized.message=must be normalized +org.apache.fineract.common.validation.ParametersScriptAssert.message=script expression "{script}" didn't evaluate to true +org.apache.fineract.common.validation.Range.message=must be between {min} and {max} +org.apache.fineract.common.validation.ScriptAssert.message=script expression "{script}" didn't evaluate to true +org.apache.fineract.common.validation.UniqueElements.message=must only contain unique elements +org.apache.fineract.common.validation.URL.message=must be a valid URL +org.apache.fineract.common.validation.UUID.message=must be a valid UUID +org.apache.fineract.common.validation.br.CNPJ.message=invalid Brazilian corporate taxpayer registry number (CNPJ) +org.apache.fineract.common.validation.br.CPF.message=invalid Brazilian individual taxpayer registry number (CPF) +org.apache.fineract.common.validation.br.TituloEleitoral.message=invalid Brazilian Voter ID card number +org.apache.fineract.common.validation.pl.REGON.message=invalid Polish Taxpayer Identification Number (REGON) +org.apache.fineract.common.validation.pl.NIP.message=invalid VAT Identification Number (NIP) +org.apache.fineract.common.validation.pl.PESEL.message=invalid Polish National Identification Number (PESEL) +org.apache.fineract.common.validation.ru.INN.message=invalid Russian taxpayer identification number (INN) +org.apache.fineract.common.validation.time.DurationMax.message=must be shorter than${inclusive == true ? ' or equal to' : ''}${days == 0 ? '' : days == 1 ? ' 1 day' : ' ' += days += ' days'}${hours == 0 ? '' : hours == 1 ? ' 1 hour' : ' ' += hours += ' hours'}${minutes == 0 ? '' : minutes == 1 ? ' 1 minute' : ' ' += minutes += ' minutes'}${seconds == 0 ? '' : seconds == 1 ? ' 1 second' : ' ' += seconds += ' seconds'}${millis == 0 ? '' : millis == 1 ? ' 1 milli' : ' ' += millis += ' millis'}${nanos == 0 ? '' : nanos == 1 ? ' 1 nano' : ' ' += nanos += ' nanos'} +org.apache.fineract.common.validation.time.DurationMin.message=must be longer than${inclusive == true ? ' or equal to' : ''}${days == 0 ? '' : days == 1 ? ' 1 day' : ' ' += days += ' days'}${hours == 0 ? '' : hours == 1 ? ' 1 hour' : ' ' += hours += ' hours'}${minutes == 0 ? '' : minutes == 1 ? ' 1 minute' : ' ' += minutes += ' minutes'}${seconds == 0 ? '' : seconds == 1 ? ' 1 second' : ' ' += seconds += ' seconds'}${millis == 0 ? '' : millis == 1 ? ' 1 milli' : ' ' += millis += ' millis'}${nanos == 0 ? '' : nanos == 1 ? ' 1 nano' : ' ' += nanos += ' nanos'} +# dummy +org.apache.fineract.dummy.request.content.not-empty=Dummy request content must have a value diff --git a/fineract-command-jdbc/dependencies.gradle b/fineract-command-jdbc/dependencies.gradle index 6027c1f7788..838ef806425 100644 --- a/fineract-command-jdbc/dependencies.gradle +++ b/fineract-command-jdbc/dependencies.gradle @@ -43,6 +43,10 @@ dependencies { annotationProcessor 'org.mapstruct:mapstruct-processor' testImplementation 'org.springframework.boot:spring-boot-liquibase' + // @Retry is an AspectJ aspect, so without this the annotations read as present and do nothing; the application + // that uses this module brings it, and the retry tests need it here to exercise the real behaviour + testImplementation 'org.aspectj:aspectjweaver' + testImplementation(project(path: ':fineract-command-test')) testImplementation ('org.springframework.boot:spring-boot-starter-test') { exclude group: 'com.jayway.jsonpath', module: 'json-path' diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java new file mode 100644 index 00000000000..4f5d110ced7 --- /dev/null +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandConstants.java @@ -0,0 +1,30 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + +public final class JdbcCommandConstants { + + private JdbcCommandConstants() {} + + public static final String COMMAND_JDBC_PROPERTIES_PREFIX = COMMAND_PROPERTIES_PREFIX + ".jdbc"; + public static final String COMMAND_JDBC_PROPERTY_ENABLED = COMMAND_JDBC_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_JDBC_STORE_BASE_PACKAGE = "org.apache.fineract.command.jdbc.store"; +} diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java index d7e0e2ebace..8ad38a104ca 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/JdbcCommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.jdbc; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import lombok.AllArgsConstructor; @@ -32,7 +34,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command.jdbc") +@ConfigurationProperties(prefix = COMMAND_JDBC_PROPERTIES_PREFIX) public final class JdbcCommandProperties implements Serializable { @Serial diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java index c7603d54940..813ed6a8247 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/starter/JdbcCommandAutoConfiguration.java @@ -18,6 +18,9 @@ */ package org.apache.fineract.command.jdbc.starter; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_PROPERTY_ENABLED; +import static org.apache.fineract.command.jdbc.JdbcCommandConstants.COMMAND_JDBC_STORE_BASE_PACKAGE; + import java.util.List; import org.apache.fineract.command.jdbc.JdbcCommandProperties; import org.apache.fineract.command.jdbc.store.converter.JsonNodeReadingConverter; @@ -31,8 +34,8 @@ @AutoConfiguration @EnableConfigurationProperties(JdbcCommandProperties.class) -@ComponentScan("org.apache.fineract.command.jdbc.store") -@ConditionalOnProperty(value = "fineract.command.jdbc.enabled", havingValue = "true") +@ComponentScan(COMMAND_JDBC_STORE_BASE_PACKAGE) +@ConditionalOnProperty(value = COMMAND_JDBC_PROPERTY_ENABLED, havingValue = "true") public class JdbcCommandAutoConfiguration { @Bean diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java index c943b0578e6..d320201f596 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/JdbcCommandStore.java @@ -21,29 +21,34 @@ 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; import java.nio.file.Path; +import java.time.Instant; 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.CommandReplay; import org.apache.fineract.command.core.CommandStore; import org.apache.fineract.command.jdbc.JdbcCommandProperties; -import org.apache.fineract.command.jdbc.store.domain.CommandEntity; -import org.apache.fineract.command.jdbc.store.domain.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.jdbc.store.mapping.JsonCommandMapper; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.context.event.ApplicationStartedEvent; import org.springframework.context.event.EventListener; +import org.springframework.dao.DuplicateKeyException; import org.springframework.stereotype.Component; +import tools.jackson.databind.JsonNode; import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.node.ObjectNode; @Slf4j @RequiredArgsConstructor @@ -51,53 +56,120 @@ @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 JsonCommandMapper jsonMapper; + private final JdbcCommandRepository repository; private final ObjectMapper objectMapper; private final JdbcCommandProperties properties; @Override - @SuppressWarnings("unchecked") - public T getRequestById(Long id) { - return (T) repository.findById(id).map(CommandEntity::getRequest) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public Command getById(Long id) { + return repository.findById(id).map(mapper::map).orElse(null); } @Override - @SuppressWarnings("unchecked") - public T getResponseById(Long id) { - return (T) repository.findById(id).map(CommandEntity::getResponse) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public Command getByKey(String key, String distinctor) { + return repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor).map(mapper::map).orElse(null); } @Override - public org.apache.fineract.command.core.CommandState getStateById(Long id) { - return repository.findById(id).map(CommandEntity::getState).orElse(UNKNOWN); + public boolean existsByKey(String key, String distinctor) { + return repository.existsByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor); } @Override - @SuppressWarnings("unchecked") - public T getRequestByKey(String key) { - return (T) repository.findOneByIdempotencyKey(key).map(CommandEntity::getRequest) - .map(json -> objectMapper.convertValue(json, forName(json.get(COMMAND_JSON_CLASS_ATTRIBUTE).asString()))).orElse(null); + public CommandReplay getReplayByKey(String key, String distinctor) { + return repository.findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(key, distinctor) + .map(entity -> new CommandReplay(entity.getState(), entity.getResponseStatusCode(), + replayResponse(key, distinctor, entity.getResponse()), entity.getCreatedAt())) + .orElseGet(() -> new CommandReplay(UNKNOWN, null, 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 - @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); + @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) { + // the claim's age is what tells an abandoned claim from a running one, so it must never be stored without one. + // The timestamp hook normally sets it as the request arrives, but it can be switched off; set on the command + // rather than only on the row, so that the audit hooks rewriting the row later keep the same value + if (isNull(command.getCreatedAt())) { + command.setCreatedAt(Instant.now()); + } + + final var commandEntity = mapper.map(command); + + commandEntity.setState(UNDER_PROCESSING); + + 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) { + if (isDuplicateKey(e)) { + log.debug("Idempotency key {} (distinctor '{}') is already claimed", command.getIdempotencyKey(), + command.getCustomIdempotencyDistinctor()); + + return false; + } + + throw e; + } } @Override - public CommandState getStateByKey(String key) { - return repository.findOneByIdempotencyKey(key).map(CommandEntity::getState).orElse(UNKNOWN); + 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(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 +191,18 @@ 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(); + + // 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())) { @@ -137,9 +220,15 @@ void onStartup() { } } - @SneakyThrows - private Class forName(String clazz) { - return Class.forName(clazz); + // Spring Data JDBC wraps the translated exception in a DbActionExecutionException, so the whole chain is inspected + private static boolean isDuplicateKey(Throwable t) { + for (var current = t; current != null; current = current.getCause()) { + if (current instanceof DuplicateKeyException) { + return true; + } + } + + return false; } private void write(Command command) throws IOException { diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java index c25c79baa74..afa37fa1290 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandEntity.java @@ -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,9 +72,26 @@ 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; + + @Column("action_name") + private String actionName; + @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 new file mode 100644 index 00000000000..9f6d672daf7 --- /dev/null +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/JdbcCommandRepository.java @@ -0,0 +1,72 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +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 findOneByIdempotencyKeyAndCustomIdempotencyDistinctor(String idempotencyKey, + String customIdempotencyDistinctor); + + 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/domain/StoredCommand.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java new file mode 100644 index 00000000000..0c070ceb56e --- /dev/null +++ b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/StoredCommand.java @@ -0,0 +1,50 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc.store.domain; + +import lombok.Data; +import lombok.EqualsAndHashCode; +import org.apache.fineract.command.core.Command; + +/** + * A command read back out of the command table. + * + *

+ * Every command declares its entity and action in code, which is what makes them impossible to forget. A command + * reconstructed from a stored row has no code to ask - the class that declared them is not involved - so it carries the + * names that were recorded with it instead. + */ +@Data +@EqualsAndHashCode(callSuper = true) +public class StoredCommand extends Command { + + private String entityName; + + private String actionName; + + @Override + public String entityName() { + return entityName; + } + + @Override + public String actionName() { + return actionName; + } +} diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandMapper.java b/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java similarity index 80% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandMapper.java rename to fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JdbcCommandMapper.java index b83867335ef..86f52168d6b 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 @@ -23,12 +23,12 @@ 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; -@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") @@ -43,7 +43,10 @@ public interface CommandMapper { @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") @Mapping(ignore = true, target = "state") @Mapping(ignore = true, target = "response") CommandEntity map(Command source); @@ -60,12 +63,16 @@ public interface CommandMapper { @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.customIdempotencyDistinctor", target = "customIdempotencyDistinctor") @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/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 85% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/CommandJsonMapper.java rename to fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/mapping/JsonCommandMapper.java index dfcd2103836..1e3290430ce 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; @@ -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 ac42af8aafe..0b55e10eab8 100644 --- a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/module-changelog-master.xml @@ -24,4 +24,9 @@ xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.1.xsd"> + + + + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml new file mode 100644 index 00000000000..e07e9a475c8 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0003_idempotency_key_unique.xml @@ -0,0 +1,69 @@ + + + + + + Make idempotency keys unique without losing any audit history. Where several rows share a key, + the earliest one keeps it and the surplus rows get their row ID appended, so the original key + stays readable and the record survives. No command record is deleted. + + Two details are deliberate: the rows are selected by ID and wrapped in a derived table because + MySQL cannot reference the UPDATE target table directly in a subquery (error 1093), and the + existing key is truncated before the suffix is appended so the result still fits varchar(255). + + + + + 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/0004_command_response_cache.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml new file mode 100644 index 00000000000..9af3d73d007 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0004_command_response_cache.xml @@ -0,0 +1,37 @@ + + + + + + A repeated request is normally answered from the command's own result, which the web layer renders with + the status it derived the first time, so nothing about the original response has to be recorded for it. + This column covers the case that leaves no result behind - a failure, whose answer comes from an exception + mapper, and an answer that is not JSON. There the recorded answer is thrown rather than returned, and + nothing else could say what status to use. + + + + + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml new file mode 100644 index 00000000000..0063da529c1 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0005_command_action_entity.xml @@ -0,0 +1,65 @@ + + + + + + + Which entity a command acts on and what it does to it, in the vocabulary of m_permission. Without them a + command record cannot be found by an audit search or a checker inbox, both of which are defined in terms + of these two names, and the permission governing maker-checker approval - the action and entity joined + with _CHECKER - cannot be derived. The approval columns are already on this table; this is what they need + to become usable. + + Not null, because a row without them is invisible to everything that reads this table by name. Rows that + predate this column are backfilled as UNKNOWN: they were written before commands recorded it, and saying + so is better than implying they acted on an entity called "". + + + + + + + + + + + diff --git a/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml new file mode 100644 index 00000000000..3f63e70e409 --- /dev/null +++ b/fineract-command-jdbc/src/main/resources/db/changelog/tenant/module/command/parts/0006_idempotency_key_distinctor.xml @@ -0,0 +1,70 @@ + + + + + + + What an idempotency key is unique together with, as the configured CustomIdempotencyDistinctor computes it + when the key is claimed. The empty string means nothing distinguishes the key, which is what every existing + row gets and what a command without a key is stored with: not null, so that the composite unique constraint + below compares two empty values as equal rather than treating two nulls as distinct. + + + + + + + + + + Make the idempotency key unique together with its distinctor. Added before the key-only constraint is + dropped, so there is no moment at which the key is not unique. Every existing row has the empty distinctor + and the key-only constraint already holds, so no existing row can violate this one. + + + + + + Drop the key-only unique constraint, which would otherwise still refuse the same key under a different + distinctor. + + + + + + + + diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java new file mode 100644 index 00000000000..7d9aec2791a --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandIdempotencyKeyMigrationTest.java @@ -0,0 +1,206 @@ +/** + * 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."); + + // the key-only constraint cannot be restored over a key stored under two distinctors, which is the + // rollback's documented limit; the test removes the row so that it can roll back past it + delete(connection, 104); + } + + rollbackUniqueConstraint(container, context); + + try (var connection = connect(container)) { + insert(connection, 102, "KEEP-1"); + assertEquals(2, count(connection, "idempotency_key = 'KEEP-1'"), "After rollback duplicate keys should be accepted again."); + } + } + + private static Connection connect(JdbcDatabaseContainer container) throws SQLException { + return DriverManager.getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword()); + } + + // note: Liquibase closes the connection it was given, so it always gets one of its own + private void migrate(JdbcDatabaseContainer container, String context) throws Exception { + try (var connection = connect(container); var liquibase = liquibase(connection)) { + liquibase.update(new Contexts(context), new LabelExpression()); + } + } + + /** + * Reverts the unique constraint, which means also reverting the response-cache, action/entity and distinctor + * changesets stacked on top of it. Both databases apply the same number of changesets from that point on, so this + * count has to grow with every changeset added after 0003. + */ + private void rollbackUniqueConstraint(JdbcDatabaseContainer container, String context) throws Exception { + try (var connection = connect(container); var liquibase = liquibase(connection)) { + liquibase.rollback(6, 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 delete(Connection connection, long id) throws SQLException { + try (var statement = connection.prepareStatement("DELETE FROM m_command WHERE id = ?")) { + statement.setLong(1, id); + statement.executeUpdate(); + } + } + + private static void insert(Connection connection, long id, String key) throws SQLException { + try (var statement = connection.prepareStatement("INSERT INTO m_command (id, idempotency_key, state) VALUES (?, ?, 'PROCESSED')")) { + statement.setLong(1, id); + 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 00000000000..c74480f633e --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/IdempotencyKeyLookupCoverageTest.java @@ -0,0 +1,85 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.lang.reflect.Method; +import java.lang.reflect.Parameter; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Locale; +import org.apache.fineract.command.core.CommandStore; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.junit.jupiter.api.Test; +import org.springframework.data.jdbc.repository.query.Query; + +/** + * Holds every lookup of a command by its idempotency key to also matching its distinctor. + * + *

+ * The key is unique only together with {@code custom_idempotency_distinctor}, so the same key can be on several rows. A + * lookup by the key alone finds whichever of them comes first - a repeat answered with another command's result, or a + * response recorded against another command's row - and a derived single-row finder fails outright. Nothing else + * notices while every row under a key has the same distinctor, which is why this is checked by name and query text + * rather than left to a test that happens to use two distinctors. + */ +class IdempotencyKeyLookupCoverageTest { + + @Test + void everyRepositoryQueryByKeyAlsoMatchesTheDistinctor() { + var keyOnly = new ArrayList(); + + for (Method method : JdbcCommandRepository.class.getDeclaredMethods()) { + var query = method.getAnnotation(Query.class); + + if (query != null) { + var sql = query.value().toLowerCase(Locale.ROOT); + + if (sql.contains("idempotency_key") && !sql.contains("custom_idempotency_distinctor")) { + keyOnly.add(method.getName() + ": " + query.value().strip()); + } + } else if (method.getName().contains("IdempotencyKey") && !method.getName().contains("CustomIdempotencyDistinctor")) { + keyOnly.add(method.getName()); + } + } + + assertThat(keyOnly).as("These repository methods look a command up by its idempotency key without its distinctor. Add " + + "custom_idempotency_distinctor to the query, or AndCustomIdempotencyDistinctor to the derived finder.").isEmpty(); + } + + @Test + void everyStoreMethodTakingAKeyAlsoTakesTheDistinctor() { + var keyOnly = new ArrayList(); + + for (Method method : CommandStore.class.getDeclaredMethods()) { + var names = Arrays.stream(method.getParameters()).map(Parameter::getName).toList(); + + assertThat(Arrays.stream(method.getParameters()).allMatch(Parameter::isNamePresent)) + .as("Parameter names must be compiled in (-parameters) for this check to mean anything.").isTrue(); + + if (names.contains("key") && !names.contains("distinctor")) { + keyOnly.add(method.getName() + names); + } + } + + assertThat(keyOnly).as("These store methods take an idempotency key without its distinctor, so they cannot tell apart the " + + "commands sharing that key.").isEmpty(); + } +} diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java similarity index 89% rename from fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java rename to fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java index df2b2e80285..d8440147e96 100644 --- a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/CommandRepositoryTest.java +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandRepositoryTest.java @@ -22,8 +22,8 @@ import java.time.Instant; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.jdbc.store.domain.CommandRepository; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; +import org.apache.fineract.command.jdbc.store.domain.JdbcCommandRepository; +import org.apache.fineract.command.jdbc.store.mapping.JdbcCommandMapper; import org.apache.fineract.command.test.CommandBaseTest; import org.apache.fineract.command.test.sample.command.DummyCommand; import org.apache.fineract.command.test.sample.data.DummyRequest; @@ -36,13 +36,13 @@ @Slf4j @SpringBootTest @ContextConfiguration(classes = TestConfiguration.class) -class CommandRepositoryTest extends CommandBaseTest { +class JdbcCommandRepositoryTest extends CommandBaseTest { @Autowired - protected CommandRepository commandRepository; + protected JdbcCommandRepository commandRepository; @Autowired - protected CommandMapper commandMapper; + protected JdbcCommandMapper commandMapper; @Test void save() { diff --git a/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreRetryTest.java new file mode 100644 index 00000000000..d133d13f082 --- /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 00000000000..f9cb9f5f779 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/JdbcCommandStoreTest.java @@ -0,0 +1,414 @@ +/** + * 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 aClaimIsAlwaysStoredWithItsTime() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + // as when the timestamp hook is switched off + command.setCreatedAt(null); + + assertTrue(store.claim(command)); + assertNotNull(command.getCreatedAt(), "The claim time must be kept on the command, so the audit hooks write it back."); + assertNotNull(store.getReplayByKey(key, "").claimedAt(), + "Without a claim time an abandoned claim can never be told from a running one, and is answered 425 for ever."); + } + + @Test + public void aKeyIsUniqueTogetherWithItsDistinctor() { + var key = UUID.randomUUID().toString(); + var loan = command(key, "hello"); + var client = command(key, "hello"); + var loanAgain = command(key, "hello"); + + loan.setCustomIdempotencyDistinctor("LOAN|CREATE"); + client.setCustomIdempotencyDistinctor("CLIENT|CREATE"); + loanAgain.setCustomIdempotencyDistinctor("LOAN|CREATE"); + + assertTrue(store.claim(loan), "The first claim of a key under a distinctor should succeed."); + assertTrue(store.claim(client), "The same key under another distinctor is a different command."); + assertFalse(store.claim(loanAgain), "The same key under the same distinctor is a repeat."); + + assertTrue(store.existsByKey(key, "LOAN|CREATE")); + assertTrue(store.existsByKey(key, "CLIENT|CREATE")); + assertFalse(store.existsByKey(key, ""), "A key claimed only under distinctors is not claimed under none."); + } + + @Test + public void aRepeatIsAnsweredFromTheRowWithItsOwnDistinctor() { + var key = UUID.randomUUID().toString(); + var loan = processed(key, "loan"); + var client = command(key, "client"); + + loan.getCommand().setCustomIdempotencyDistinctor("LOAN|CREATE"); + client.setCustomIdempotencyDistinctor("CLIENT|CREATE"); + + store.claim(loan.getCommand()); + store.store(loan); + store.claim(client); + store.recordResponse(key, "CLIENT|CREATE", 400, "{\"error\":\"bad request\"}"); + + assertEquals(PROCESSED, store.getReplayByKey(key, "LOAN|CREATE").state()); + assertEquals("LOAN", ((DummyResponse) store.getReplayByKey(key, "LOAN|CREATE").response()).getContent()); + assertNull(store.getReplayByKey(key, "LOAN|CREATE").statusCode(), "Recording the other row's answer must not touch this one."); + + assertEquals(UNDER_PROCESSING, store.getReplayByKey(key, "CLIENT|CREATE").state()); + assertEquals(400, store.getReplayByKey(key, "CLIENT|CREATE").statusCode()); + + assertTrue(store.matchesStoredRequest(key, "LOAN|CREATE", DummyRequest.builder().content("loan").build())); + assertFalse(store.matchesStoredRequest(key, "LOAN|CREATE", DummyRequest.builder().content("client").build()), + "A request is compared only with the request stored under the same distinctor."); + assertEquals(UNKNOWN, store.getReplayByKey(key, "").state(), "No row was stored under the empty distinctor."); + } + + @Test + public void aCommandWithNoDistinctorIsStoredWithTheEmptyOne() { + var key = UUID.randomUUID().toString(); + var command = command(key, "hello"); + + command.setCustomIdempotencyDistinctor(null); + + assertTrue(store.claim(command), "The column does not take null, so a missing distinctor has to be stored as empty."); + assertEquals("", store.getByKey(key, "").getCustomIdempotencyDistinctor()); + } + + @Test + public void commandsWithoutAKeyNeverConflict() { + assertTrue(store.claim(command(null, "hello")), "A command without an idempotency key should always be claimable."); + 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."); + assertNotNull(inFlight.claimedAt(), "When the key was claimed is what tells a slow command from an abandoned one."); + assertNull(inFlight.statusCode(), "An in-flight command has not been answered yet."); + assertNull(inFlight.response(), "An in-flight command has nothing to replay."); + + 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 00000000000..3ed900318d2 --- /dev/null +++ b/fineract-command-jdbc/src/test/java/org/apache/fineract/command/jdbc/RetryPolicyTest.java @@ -0,0 +1,90 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.jdbc; + +import static org.assertj.core.api.Assertions.assertThat; + +import io.github.resilience4j.retry.RetryRegistry; +import io.github.resilience4j.springboot.retry.autoconfigure.RetryAutoConfiguration; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.dao.CannotAcquireLockException; +import org.springframework.dao.DataIntegrityViolationException; +import org.springframework.dao.DeadlockLoserDataAccessException; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.dao.QueryTimeoutException; +import org.springframework.dao.RecoverableDataAccessException; +import org.springframework.dao.TransientDataAccessResourceException; + +/** + * Pins which failures are worth another attempt, and proves the policy reaches an instance that does not state one. + * + *

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

+ * The widened list is set on the command store alone. The jobs that post interest and run close-of-business keep the + * narrower one they already had, because a connection lost during commit leaves the outcome of that commit unknown, and + * retrying an interest posting there is how it gets posted twice. Writing the command row is safe to retry for the + * opposite reason: the idempotency key is unique, so a second attempt cannot write the row twice. + */ +class RetryPolicyTest { + + private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(AopAutoConfiguration.class, RetryAutoConfiguration.class)).withPropertyValues( + // the same two lines the application sets for this instance, and for this instance only + "resilience4j.retry.instances.commandStore.retryExceptions=" + + "org.springframework.dao.TransientDataAccessException,org.springframework.dao.RecoverableDataAccessException", + "resilience4j.retry.instances.commandStore.ignoreExceptions=org.springframework.dao.DataIntegrityViolationException", + "resilience4j.retry.instances.commandStore.max-attempts=3"); + + @Test + void aFailureThatMightNotHappenAgainIsRetried() { + contextRunner.run(context -> { + var predicate = policyOf(context.getBean(RetryRegistry.class)); + + assertThat(predicate.test(new DeadlockLoserDataAccessException("deadlock", null))).as("a deadlock").isTrue(); + assertThat(predicate.test(new CannotAcquireLockException("lock timeout"))).as("a lock that could not be taken").isTrue(); + assertThat(predicate.test(new QueryTimeoutException("timeout"))).as("a query timeout").isTrue(); + assertThat(predicate.test(new TransientDataAccessResourceException("connection reset"))).as("a dropped connection").isTrue(); + assertThat(predicate.test(new RecoverableDataAccessException("connection lost"))).as("a recoverable failure").isTrue(); + }); + } + + @Test + void aFailureThatWouldHappenEveryTimeIsNotRetried() { + contextRunner.run(context -> { + var predicate = policyOf(context.getBean(RetryRegistry.class)); + + assertThat(predicate.test(new DuplicateKeyException("the key is already claimed"))) + .as("a unique constraint is a verdict, not a mishap").isFalse(); + assertThat(predicate.test(new DataIntegrityViolationException("a column will not take that value"))) + .as("the data is wrong and will still be wrong next time").isFalse(); + }); + } + + private static java.util.function.Predicate policyOf(RetryRegistry registry) { + return registry.retry("commandStore").getRetryConfig().getExceptionPredicate(); + } +} diff --git a/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml new file mode 100644 index 00000000000..6b22baa064c --- /dev/null +++ b/fineract-command-jdbc/src/test/resources/liquibase-test/command-migration-test-changelog.xml @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java index babe94260d1..1b37de2469d 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/api/DummyApiController.java @@ -28,6 +28,9 @@ import lombok.extern.slf4j.Slf4j; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.test.sample.command.DummyCommand; +import org.apache.fineract.command.test.sample.command.DummyErrorCommand; +import org.apache.fineract.command.test.sample.data.DummyErrorRequest; +import org.apache.fineract.command.test.sample.data.DummyErrorResponse; import org.apache.fineract.command.test.sample.data.DummyRequest; import org.apache.fineract.command.test.sample.data.DummyResponse; import org.springframework.scheduling.annotation.Async; @@ -59,6 +62,18 @@ DummyResponse dummySync(@RequestHeader(value = COMMAND_HTTP_HEADER_TENANT_ID, re return result.get(); } + /** Always fails, so that the behaviour of a failing command can be exercised over HTTP. */ + @PostMapping("/error") + DummyErrorResponse dummyError(@RequestBody DummyErrorRequest request) { + var command = new DummyErrorCommand(); + + command.setPayload(request); + + Supplier result = pipeline.dispatch(command); + + return result.get(); + } + @Async @PostMapping("/async") CompletableFuture dummyAsync(@RequestHeader(value = COMMAND_HTTP_HEADER_TENANT_ID, required = false) String tenantId, diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java index 14829a781da..25487893438 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class DummyCommand extends Command {} +public class DummyCommand extends Command { + + @Override + public String entityName() { + return "DUMMY"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java index 11e07ed0576..020637dde5c 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/command/DummyErrorCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class DummyErrorCommand extends Command {} +public class DummyErrorCommand extends Command { + + @Override + public String entityName() { + return "DUMMY"; + } + + @Override + public String actionName() { + return "ERROR"; + } +} diff --git a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java index df9d4ee2cba..8e0a2d0fd01 100644 --- a/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java +++ b/fineract-command-test/src/main/java/org/apache/fineract/command/test/sample/data/DummyRequest.java @@ -21,13 +21,16 @@ import jakarta.validation.constraints.NotEmpty; import java.io.Serial; import java.io.Serializable; +import java.math.BigDecimal; +import java.time.LocalDate; +import java.time.OffsetDateTime; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; import lombok.experimental.FieldNameConstants; -@Builder +@Builder(toBuilder = true) @Data @NoArgsConstructor @AllArgsConstructor @@ -39,4 +42,24 @@ public class DummyRequest implements Serializable { @NotEmpty(message = "{org.apache.fineract.dummy.content.not-empty}") private String content; + + /** + * Present so that tests exercise the field types real requests carry. Each of these serialises differently, and + * several of them change shape if a stored request or response is parsed and re-rendered rather than kept as it was + * written. + */ + private Long referenceId; + + private Integer count; + + private Boolean flag; + + private BigDecimal amount; + + /** Beyond what a double can represent, so a comparison that rounds through one would miss a real difference. */ + private BigDecimal preciseAmount; + + private LocalDate businessDate; + + private OffsetDateTime timestamp; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java index 8441f3ca620..1e66d0d00b1 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/Command.java @@ -26,7 +26,7 @@ @Data @FieldNameConstants -public class Command implements Serializable { +public abstract class Command implements Serializable { @Serial private static final long serialVersionUID = 1L; @@ -35,6 +35,13 @@ public 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; @@ -58,4 +65,29 @@ 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 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/CommandConstants.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java index 35f9c1db86f..d56cb188dfd 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandConstants.java @@ -22,6 +22,15 @@ public final class CommandConstants { private CommandConstants() {} + public static final String COMMAND_PROPERTIES_PREFIX = "fineract.command"; + public static final String COMMAND_PROPERTY_ENABLED = COMMAND_PROPERTIES_PREFIX + ".enabled"; + public static final String COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-servlet-headers-enabled"; + public static final String COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-timestamp-enabled"; + public static final String COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED = COMMAND_PROPERTIES_PREFIX + ".hook-username-enabled"; + public static final String COMMAND_BASE_PACKAGE = "org.apache.fineract.command"; + public static final String COMMAND_CORE_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".core"; + public static final String COMMAND_HOOK_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".hook"; + public static final String COMMAND_IMPLEMENTATION_BASE_PACKAGE = COMMAND_BASE_PACKAGE + ".implementation"; public static final String COMMAND_JSON_CLASS_ATTRIBUTE = "@class"; public static final String COMMAND_HTTP_HEADER_REQUEST_ID = "x-fineract-request-id"; public static final String COMMAND_HTTP_HEADER_TENANT_ID = "Fineract-Platform-TenantId"; diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java new file mode 100644 index 00000000000..c7a527dd68b --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandContext.java @@ -0,0 +1,53 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +import static org.apache.fineract.command.core.CommandState.UNDER_PROCESSING; + +import java.io.Serial; +import java.io.Serializable; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Data; +import lombok.NoArgsConstructor; +import lombok.experimental.FieldNameConstants; + +@Builder +@Data +@NoArgsConstructor +@AllArgsConstructor +@FieldNameConstants +public final class CommandContext implements Serializable { + + @Serial + private static final long serialVersionUID = 1L; + + private Command command; + + private RES response; + + private Throwable error; + + @Builder.Default + private CommandState state = UNDER_PROCESSING; + + private boolean skipExecution; + + private boolean skipHooks; +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java index ce479ab7f66..d252ce06cba 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookAfter.java @@ -21,5 +21,5 @@ @FunctionalInterface public interface CommandHookAfter { - void onAfter(Command command, RES response); + void onAfter(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java index 7f5af0c6dc9..22d1ad09f4f 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookBefore.java @@ -19,7 +19,7 @@ package org.apache.fineract.command.core; @FunctionalInterface -public interface CommandHookBefore { +public interface CommandHookBefore { - void onBefore(Command command); + void onBefore(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java index 2730dd68729..9eb4c7a026c 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookError.java @@ -19,7 +19,7 @@ package org.apache.fineract.command.core; @FunctionalInterface -public interface CommandHookError { +public interface CommandHookError { - void onError(Command command, Throwable error); + void onError(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java index ca9f2d5e54c..cf589ae69ff 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandHookManager.java @@ -18,11 +18,12 @@ */ package org.apache.fineract.command.core; +@SuppressWarnings("rawtypes") public interface CommandHookManager { - void before(Command command); + void before(CommandContext ctx); - void after(Command command, Object response); + void after(CommandContext ctx); - void error(Command command, Throwable error); + void error(CommandContext ctx); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java index 6450cb58901..086cb6a3c1a 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandProperties.java @@ -18,6 +18,8 @@ */ package org.apache.fineract.command.core; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTIES_PREFIX; + import java.io.Serial; import java.io.Serializable; import java.util.HashMap; @@ -34,7 +36,7 @@ @NoArgsConstructor @AllArgsConstructor @FieldNameConstants -@ConfigurationProperties(prefix = "fineract.command") +@ConfigurationProperties(prefix = COMMAND_PROPERTIES_PREFIX) public final class CommandProperties implements Serializable { @Serial @@ -47,5 +49,11 @@ public final class CommandProperties implements Serializable { private Map hooks = new HashMap<>(); @Builder.Default - private String idemPotencyKeyHeaderName = "Idempotency-Key"; + private Boolean hookServletHeadersEnabled = true; + + @Builder.Default + private Boolean hookTimestampEnabled = true; + + @Builder.Default + private Boolean hookUsernameEnabled = true; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java new file mode 100644 index 00000000000..1f43fcf8c57 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandReplay.java @@ -0,0 +1,39 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +import java.time.Instant; + +/** + * What is known about a command already stored under an idempotency key: enough to answer a repeated request exactly as + * the original one was answered, without executing anything. + * + * @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 claimedAt + * when the command was claimed, used to tell a command that is still running from one that never finished + * @param response + * the response object the original command produced, rehydrated from the command store, {@code null} if it + * never completed. It is handed back to the web layer as an object rather than as text so that the same + * serializer that rendered the original answer renders the replay, which is what makes the two identical. + */ +public record CommandReplay(CommandState state, Integer statusCode, Object response, Instant claimedAt) { +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java index a93135c9e8e..db98633b4de 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/CommandStore.java @@ -20,17 +20,47 @@ public interface CommandStore { - T getRequestById(Long id); + Command getById(Long id); - T getResponseById(Long id); + /* + * 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. + */ - CommandState getStateById(Long id); + Command getByKey(String key, String distinctor); - T getRequestByKey(String key); + boolean existsByKey(String key, String distinctor); - T getResponseByKey(String key); + /** + * @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); - CommandState getStateByKey(String key); + /** + * Records what the original request was answered with, for the parts a command cannot know: the status code always, + * and the body only when the command stored no result of its own. A stored result is never replaced, because a + * replay is rendered from that result rather than from captured text. + */ + void recordResponse(String key, String distinctor, int statusCode, String body); - void store(Command command, Object response, CommandState state); + /** + * Atomically claims the command's idempotency key, together with its distinctor, by persisting it, so that no other + * request can execute a command under the same key and distinctor. Must not be retried, and the conflict must not + * be swallowed. + * + * @return {@code true} if the key was claimed by this call, {@code false} if it was already claimed + */ + 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-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java b/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java index 6af72daf36d..286b71e3784 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/HookableCommand.java @@ -20,12 +20,11 @@ /** * Implemented by commands whose successful execution must notify the webhooks registered for its event, as the legacy - * command processing does for every command. The names are the entity and action a hook subscribes to, e.g. - * {@code DOCUMENT} and {@code CREATE}. + * command processing does for every command. + * + *

+ * A marker only. The entity and action a hook subscribes to are {@link Command#entityName()} and + * {@link Command#actionName()}, which every command declares; this says nothing more than whether webhooks are notified + * for this one. */ -public interface HookableCommand { - - String hookEntityName(); - - String hookActionName(); -} +public interface HookableCommand {} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java b/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java new file mode 100644 index 00000000000..7eafbe62b7d --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/RecoverableCommandErrorClassifier.java @@ -0,0 +1,39 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core; + +/** + * Decides whether a command failed in a way that a retry under the same idempotency key should execute again, rather + * than be answered with the stored failure. + * + *

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

+ * The idempotency module falls back to treating nothing as recoverable. The application supplies the real rules, which + * in Fineract are the same ones the legacy command processing applies. + */ +@FunctionalInterface +public interface RecoverableCommandErrorClassifier { + + boolean isRecoverable(Throwable error); +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java new file mode 100644 index 00000000000..92868fcbff7 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/AbstractCommandIdempotencyException.java @@ -0,0 +1,57 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +import lombok.Getter; + +/** + * Base of the answers given to a request that repeats an idempotency key. The request is never executed again; it is + * answered from what was stored for the original one, which is why every subclass carries a status code and a response + * rather than a message. + * + *

+ * The response is the command's own result object, rehydrated from the command store, not pre-rendered text. Handing + * the web layer an object lets it serialize the replay exactly as it serialized the original answer. + */ +@Getter +public abstract class AbstractCommandIdempotencyException extends RuntimeException { + + /** Set on every answer served from the command store, so a client can tell a replay from a fresh execution. */ + public static final String IDEMPOTENT_CACHE_HEADER = "x-served-from-cache"; + + private final String idempotencyKey; + private final int statusCode; + private final Object response; + + protected AbstractCommandIdempotencyException(String idempotencyKey, int statusCode, Object response) { + this(idempotencyKey, statusCode, response, null); + } + + /** + * Carries what went wrong underneath, for an answer that is given because the stored result could not be used + * rather than because it could. + */ + protected AbstractCommandIdempotencyException(String idempotencyKey, int statusCode, Object response, Throwable cause) { + super("Idempotency key " + idempotencyKey + " was already used; answering with the stored result (" + statusCode + ")", cause); + + this.idempotencyKey = idempotencyKey; + this.statusCode = statusCode; + this.response = response; + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java new file mode 100644 index 00000000000..f833ffb631e --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyConflictException.java @@ -0,0 +1,37 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats an idempotency key for a different request than the one stored under it. Replaying the + * stored response would answer a question that was never asked, so the request is rejected instead. + */ +public class CommandIdempotencyConflictException extends AbstractCommandIdempotencyException { + + /** 409 Conflict - the key is in use by a different request. */ + public static final int STATUS_CODE = 409; + + public CommandIdempotencyConflictException(String idempotencyKey, Object response) { + super(idempotencyKey, STATUS_CODE, response); + } + + public CommandIdempotencyConflictException(String idempotencyKey, Object response, Throwable cause) { + super(idempotencyKey, STATUS_CODE, response, cause); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java new file mode 100644 index 00000000000..9fd9d23d4e5 --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyFailedException.java @@ -0,0 +1,31 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats the idempotency key of a command that failed. The original failure is replayed with the + * status it was first answered with, so a repeat fails exactly the way the original did. + */ +public class CommandIdempotencyFailedException extends AbstractCommandIdempotencyException { + + public CommandIdempotencyFailedException(String idempotencyKey, Integer statusCode, Object response) { + // an unknown status means the stored record is inconsistent; answering 500 beats answering nothing + super(idempotencyKey, statusCode == null ? 500 : statusCode, response); + } +} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java new file mode 100644 index 00000000000..93d24a5b3dd --- /dev/null +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyInProgressException.java @@ -0,0 +1,33 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +/** + * Thrown when a request repeats an idempotency key whose original command is still being processed. There is no result + * to replay yet, so the caller is told it asked too early and should come back. + */ +public class CommandIdempotencyInProgressException extends AbstractCommandIdempotencyException { + + /** 425 Too Early - the original command has not finished, so retrying is the right thing to do. */ + public static final int STATUS_CODE = 425; + + public CommandIdempotencyInProgressException(String idempotencyKey, Object response) { + super(idempotencyKey, STATUS_CODE, response); + } +} diff --git a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java similarity index 61% rename from fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java rename to fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java index 7e5e34ea9ad..752f8300f5c 100644 --- a/fineract-command-jdbc/src/main/java/org/apache/fineract/command/jdbc/store/domain/CommandRepository.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/core/exception/CommandIdempotencyProcessedException.java @@ -16,13 +16,15 @@ * specific language governing permissions and limitations * under the License. */ -package org.apache.fineract.command.jdbc.store.domain; +package org.apache.fineract.command.core.exception; -import java.util.Optional; -import org.springframework.data.repository.ListCrudRepository; -import org.springframework.data.repository.query.QueryByExampleExecutor; - -public interface CommandRepository extends ListCrudRepository, QueryByExampleExecutor { +/** + * Thrown when a request repeats the idempotency key of a command that completed. The original response is replayed with + * the status it was first answered with. + */ +public class CommandIdempotencyProcessedException extends AbstractCommandIdempotencyException { - Optional findOneByIdempotencyKey(String idempotencyKey); + public CommandIdempotencyProcessedException(String idempotencyKey, Integer statusCode, Object response) { + super(idempotencyKey, statusCode == null ? 200 : statusCode, response); + } } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java index b2bbeb3906b..7f07ccd87ae 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/ServletHeadersCommandHook.java @@ -20,51 +20,31 @@ import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_HEADERS; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HTTP_HEADER_IP; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED; +import static org.apache.fineract.command.util.ServletHeaderUtil.getHeader; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; -import org.apache.fineract.command.core.CommandProperties; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; -import org.springframework.web.context.request.RequestContextHolder; -import org.springframework.web.context.request.ServletRequestAttributes; @Slf4j @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_HEADERS) -@ConditionalOnProperty(value = "fineract.command.hooks.servlet-header-pre", havingValue = "true") -final class ServletHeadersCommandHook implements CommandHookBefore { - - private final CommandProperties properties; +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_SERVLET_HEADERS_ENABLED, havingValue = "true") +final class ServletHeadersCommandHook implements CommandHookBefore { @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (StringUtils.isEmpty(command.getIpAddress())) { command.setIpAddress(getHeader(COMMAND_HTTP_HEADER_IP, false)); } - if (StringUtils.isEmpty(command.getIdempotencyKey())) { - command.setIdempotencyKey(getHeader(properties.getIdemPotencyKeyHeaderName(), false)); - } - } - - private String getHeader(String name, boolean searchParameter) { - var attributes = RequestContextHolder.getRequestAttributes(); - - if (attributes instanceof ServletRequestAttributes servletAttributes) { - var value = servletAttributes.getRequest().getHeader(name.toLowerCase()); - - if (searchParameter && StringUtils.isEmpty(value)) { - value = servletAttributes.getRequest().getParameter(name.toLowerCase()); - } - - return value; - } - - return null; } } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java index 5ddbf41abc1..cf6c23f23d6 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/TimestampCommandHook.java @@ -19,11 +19,12 @@ package org.apache.fineract.command.hook; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_TIMESTAMP; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED; import java.time.Instant; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -33,11 +34,13 @@ @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_TIMESTAMP) -@ConditionalOnProperty(value = "fineract.command.hooks.timestamp-pre", havingValue = "true") -final class TimestampCommandHook implements CommandHookBefore { +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_TIMESTAMP_ENABLED, havingValue = "true") +final class TimestampCommandHook implements CommandHookBefore { @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (command.getCreatedAt() == null) { command.setCreatedAt(Instant.now()); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java b/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java index d3d0d74a43b..cfa8984973d 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/hook/UsernameCommandHook.java @@ -19,11 +19,12 @@ package org.apache.fineract.command.hook; import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_ORDER_USERNAME; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.commons.lang3.StringUtils; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookBefore; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.core.annotation.Order; @@ -34,13 +35,15 @@ @RequiredArgsConstructor @Component @Order(COMMAND_HOOK_ORDER_USERNAME) -@ConditionalOnProperty(value = "fineract.command.hooks.username-pre", havingValue = "true") -final class UsernameCommandHook implements CommandHookBefore { +@ConditionalOnProperty(value = COMMAND_PROPERTY_HOOKS_USERNAME_ENABLED, havingValue = "true") +final class UsernameCommandHook implements CommandHookBefore { private static final String DEFAULT_USERNAME = "unknown"; @Override - public void onBefore(Command command) { + public void onBefore(CommandContext ctx) { + var command = ctx.getCommand(); + if (StringUtils.isEmpty(command.getInitiatedByUsername())) { command.setInitiatedByUsername(getUsername()); } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java b/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java index 535af2dc8c8..18c279fe67f 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/implementation/DefaultCommandHookManager.java @@ -21,7 +21,7 @@ import java.util.List; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandHookAfter; import org.apache.fineract.command.core.CommandHookBefore; import org.apache.fineract.command.core.CommandHookError; @@ -41,17 +41,50 @@ public class DefaultCommandHookManager implements CommandHookManager { private final List errorHooks; @Override - public void before(Command command) { - beforeHooks.forEach(processor -> processor.onBefore(command)); + public void before(CommandContext ctx) { + for (var hookBefore : beforeHooks) { + hookBefore.onBefore(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining pre hooks after: {}", hookBefore.getClass().getCanonicalName()); + } + return; + } + } } @Override - public void after(Command command, Object response) { - afterHooks.forEach(processor -> processor.onAfter(command, response)); + public void after(CommandContext ctx) { + for (var hookAfter : afterHooks) { + hookAfter.onAfter(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining post hooks after: {}", hookAfter.getClass().getCanonicalName()); + } + return; + } + } } @Override - public void error(Command command, Throwable error) { - errorHooks.forEach(processor -> processor.onError(command, error)); + public void error(CommandContext ctx) { + for (var hookError : errorHooks) { + hookError.onError(ctx); + + if (ctx.isSkipHooks()) { + ctx.setSkipHooks(false); + + if (log.isDebugEnabled()) { + log.debug("Skipping remaining error hooks after: {}", hookError.getClass().getCanonicalName()); + } + return; + } + } } } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java b/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java index 227210e3381..546b88ca1dc 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/implementation/SynchronousCommandDispatcher.java @@ -19,11 +19,13 @@ package org.apache.fineract.command.implementation; import static java.util.Objects.requireNonNull; +import static org.apache.fineract.command.core.CommandState.PROCESSED; import java.util.function.Supplier; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.fineract.command.core.Command; +import org.apache.fineract.command.core.CommandContext; import org.apache.fineract.command.core.CommandDispatcher; import org.apache.fineract.command.core.CommandHandlerManager; import org.apache.fineract.command.core.CommandHookManager; @@ -43,17 +45,28 @@ public class SynchronousCommandDispatcher implements CommandDispatcher { public Supplier dispatch(final Command command) { requireNonNull(command, "Command must not be null"); + final var ctx = CommandContext.builder().command(command).build(); + return () -> { try { - hookManager.before(command); + hookManager.before(ctx); + + if (ctx.isSkipExecution()) { + return ctx.getResponse(); + } RES response = handlerManager.handle(command); - hookManager.after(command, response); + ctx.setResponse(response); + ctx.setState(PROCESSED); - return response; + hookManager.after(ctx); + + return ctx.getResponse(); } catch (Exception e) { - hookManager.error(command, e); + ctx.setError(e); + + hookManager.error(ctx); throw e; } diff --git a/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java b/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java index c5048b75c28..c83726eaa05 100644 --- a/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java +++ b/fineract-command/src/main/java/org/apache/fineract/command/starter/CommandConfiguration.java @@ -18,6 +18,10 @@ */ package org.apache.fineract.command.starter; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_CORE_BASE_PACKAGE; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_HOOK_BASE_PACKAGE; +import static org.apache.fineract.command.core.CommandConstants.COMMAND_IMPLEMENTATION_BASE_PACKAGE; + import org.apache.fineract.command.core.CommandProperties; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.ComponentScan; @@ -25,7 +29,7 @@ @Configuration @EnableConfigurationProperties(CommandProperties.class) -@ComponentScan("org.apache.fineract.command.core") -@ComponentScan("org.apache.fineract.command.hook") -@ComponentScan("org.apache.fineract.command.implementation") +@ComponentScan(COMMAND_CORE_BASE_PACKAGE) +@ComponentScan(COMMAND_HOOK_BASE_PACKAGE) +@ComponentScan(COMMAND_IMPLEMENTATION_BASE_PACKAGE) class CommandConfiguration {} diff --git a/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java b/fineract-command/src/main/java/org/apache/fineract/command/util/ServletHeaderUtil.java new file mode 100644 index 00000000000..9aceba02850 --- /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/CommandSampleApiTest.java b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java index 6ec9ed28d5c..1383f240c74 100644 --- a/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java +++ b/fineract-command/src/test/java/org/apache/fineract/command/CommandSampleApiTest.java @@ -36,13 +36,11 @@ import java.util.Map; import java.util.UUID; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.core.CommandProperties; import org.apache.fineract.command.test.sample.data.DummyRequest; import org.apache.fineract.command.test.sample.data.DummyResponse; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.server.LocalServerPort; import org.springframework.http.HttpEntity; @@ -69,9 +67,6 @@ class CommandSampleApiTest { private RestTemplate restTemplate; - @Autowired - private CommandProperties properties; - @BeforeEach public void setUp() { this.restTemplate = new RestTemplate(); @@ -110,8 +105,10 @@ void dummyApiSync() { restTemplate.setInterceptors(interceptors); + // this module has no command store, so the key is only carried, not acted on; the idempotency behaviour itself + // is covered by IdempotencyCheckCommandHookTest and JdbcCommandStoreTest final var headers = new HttpHeaders(); - headers.add(properties.getIdemPotencyKeyHeaderName(), idempotencyKey); + headers.add("Idempotency-Key", idempotencyKey); final var request = new HttpEntity<>(DummyRequest.builder().content(content).build(), headers); @@ -123,20 +120,10 @@ void dummyApiSync() { assertNotNull(result.getContent(), "Response body should not be null."); assertEquals(content.toUpperCase(Locale.ROOT), result.getContent(), "Wrong response content."); - // DummyResponse response = store.getResponseByKey(idempotencyKey); - // - // assertNotNull(response, "There should be a command entity stored with a response."); - // assertNotNull(response, "Response should not be null."); - // assertNotNull(response.getContent(), "Response body should not be null."); - // assertNotNull(response.getTenantId(), "Tenant ID should not be null."); - // assertEquals("dummy", response.getTenantId(), "Unexpected tenant ID."); - // assertEquals(content.toUpperCase(Locale.ROOT), response.getContent(), "Wrong response content."); - // - // log.warn("Command response: {}", response); } @Test - @Disabled // TODO: implement idempotency properly with backwards compatibility + @Disabled // needs a command store; see JdbcCommandStoreTest and IdempotencyCheckCommandHookTest void dummyApiIdempotencySync() { dummyApiIdempotency("/sync"); } diff --git a/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java b/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java new file mode 100644 index 00000000000..6bbb6e0e2c4 --- /dev/null +++ b/fineract-command/src/test/java/org/apache/fineract/command/core/exception/CommandIdempotencyExceptionTest.java @@ -0,0 +1,74 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command.core.exception; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertSame; + +import org.junit.jupiter.api.Test; + +/** + * The status codes and header below are the contract the old command processing already answers with, so a client that + * works against it keeps working against the new one. + */ +class CommandIdempotencyExceptionTest { + + private static final String KEY = "7f3a1c04"; + + @Test + void theReplayHeaderMatchesTheOneTheOldProcessingUses() { + assertEquals("x-served-from-cache", AbstractCommandIdempotencyException.IDEMPOTENT_CACHE_HEADER, + "Changing this header name would break every client that checks for a replay."); + } + + @Test + void anUnfinishedCommandAnswersTooEarly() { + var stored = new Object(); + var exception = new CommandIdempotencyInProgressException(KEY, stored); + + assertEquals(425, exception.getStatusCode(), "An unfinished command must answer 425 Too Early."); + assertSame(stored, exception.getResponse(), "The answer carries the result object, which the web layer renders."); + assertEquals(KEY, exception.getIdempotencyKey(), "The answer must name the key it is about."); + } + + @Test + void aProcessedCommandReplaysItsOwnStatus() { + assertEquals(201, new CommandIdempotencyProcessedException(KEY, 201, new Object()).getStatusCode(), + "A replay must answer with the status the original was answered with."); + assertEquals(200, new CommandIdempotencyProcessedException(KEY, null, new Object()).getStatusCode(), + "A processed command with no recorded status falls back to 200."); + } + + @Test + void aFailedCommandReplaysItsOwnFailure() { + var stored = new Object(); + var exception = new CommandIdempotencyFailedException(KEY, 400, stored); + + assertEquals(400, exception.getStatusCode(), "A repeat of a failed command must fail the same way."); + assertSame(stored, exception.getResponse(), "A repeat of a failed command carries whatever was stored for it."); + assertEquals(500, new CommandIdempotencyFailedException(KEY, null, null).getStatusCode(), + "An inconsistent record answers 500 rather than nothing at all."); + } + + @Test + void aKeyUsedForAnotherRequestConflicts() { + assertEquals(409, new CommandIdempotencyConflictException(KEY, null).getStatusCode(), + "Reusing a key for a different request is a conflict, not a replay."); + } +} diff --git a/fineract-command/src/test/resources/application-test.properties b/fineract-command/src/test/resources/application-test.properties index 6b548107d11..182badf97be 100644 --- a/fineract-command/src/test/resources/application-test.properties +++ b/fineract-command/src/test/resources/application-test.properties @@ -23,6 +23,6 @@ debug=true fineract.command.enabled=true -fineract.command.hooks.servlet-header-pre=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_PRE:true} -fineract.command.hooks.timestamp-pre=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_PRE:true} -fineract.command.hooks.username-pre=${FINERACT_COMMAND_PROCESSORS_USERNAME_PRE:true} +fineract.command.hook-servlet-headers-enabled=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADERS_ENABLED:true} +fineract.command.hook-timestamp-enabled=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_ENABLED:true} +fineract.command.hook-username-enabled=${FINERACT_COMMAND_PROCESSORS_USERNAME_ENABLED:true} diff --git a/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java b/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java new file mode 100644 index 00000000000..2f2f8a3f678 --- /dev/null +++ b/fineract-core/src/main/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapter.java @@ -0,0 +1,41 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.commands.service; + +import lombok.RequiredArgsConstructor; +import org.apache.fineract.command.core.RecoverableCommandErrorClassifier; +import org.springframework.stereotype.Component; + +/** + * Gives the new command processing the same notion of a recoverable failure as the legacy one, so that a retry under + * the same idempotency key is executed again in exactly the cases where it is today: an exception marked + * {@code RecoverableError}, or one whose error codes are all listed in the {@code idempotency-recoverable-error-codes} + * global configuration. + */ +@Component +@RequiredArgsConstructor +public class RecoverableCommandErrorClassifierAdapter implements RecoverableCommandErrorClassifier { + + private final RecoverableErrorClassifier classifier; + + @Override + public boolean isRecoverable(Throwable error) { + return error instanceof RuntimeException runtimeException && classifier.isRecoverable(runtimeException); + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java index a85b362973e..11e9a2dcde0 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/businessdate/command/BusinessDateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class BusinessDateUpdateCommand extends Command {} +public class BusinessDateUpdateCommand extends Command { + + @Override + public String entityName() { + return "BUSINESS_DATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java index a8a95889449..6b91aee79ae 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/cache/command/CacheSwitchCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CacheSwitchCommand extends Command {} +public class CacheSwitchCommand extends Command { + + @Override + public String entityName() { + return "CACHE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java index c42d79b2ebe..b406ad8785b 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/event/external/command/ExternalConfigurationsUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ExternalConfigurationsUpdateCommand extends Command {} +public class ExternalConfigurationsUpdateCommand extends Command { + + @Override + public String entityName() { + return "EXTERNAL_EVENT_CONFIGURATION"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java index 5d949c37f67..05fbd4d8269 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandEventPublisher.java @@ -25,7 +25,7 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.apache.fineract.batch.exception.ErrorInfo; -import org.apache.fineract.command.core.HookableCommand; +import org.apache.fineract.command.core.Command; import org.apache.fineract.infrastructure.core.exception.ErrorHandler; import org.apache.fineract.infrastructure.core.service.ThreadLocalContextUtil; import org.apache.fineract.infrastructure.hooks.event.HookEvent; @@ -53,7 +53,7 @@ class WebhookCommandEventPublisher { private final ObjectMapper mapper; private final ErrorHandler errorHandler; - void publishSuccess(HookableCommand hookable, Object request, Object response) { + void publishSuccess(Command hookable, Object request, Object response) { publish(hookable, request, payload -> { // As in the legacy command processing, the office and client are exposed at the top level of the payload, // where the SMS hooks look up the client to notify, and the office is cleared from the response. @@ -69,7 +69,7 @@ void publishSuccess(HookableCommand hookable, Object request, Object response) { }); } - void publishError(HookableCommand hookable, Object request, Throwable error) { + void publishError(Command hookable, Object request, Throwable error) { publish(hookable, request, payload -> { final ErrorInfo errorInfo = errorHandler.handle(ErrorHandler.getMappable(error)); payload.put("status", "Exception"); @@ -77,9 +77,9 @@ void publishError(HookableCommand hookable, Object request, Throwable error) { }); } - private void publish(HookableCommand hookable, Object request, Consumer> result) { - final String entityName = hookable.hookEntityName(); - final String actionName = hookable.hookActionName(); + private void publish(Command hookable, Object request, Consumer> result) { + final String entityName = hookable.entityName(); + final String actionName = hookable.actionName(); try { final AppUser user = context.authenticatedUser(); diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java index 4cd4e71aa9d..2d1e574cc18 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfter.java @@ -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) { - if (!(command instanceof HookableCommand hookable)) { + public void onAfter(CommandContext ctx) { + var command = ctx.getCommand(); + + if (!(command instanceof HookableCommand)) { 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()) { @@ -50,11 +55,11 @@ public void onAfter(Command command, Object response) { @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 ba4d9b71dbb..6cf9aec93c4 100644 --- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java +++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookError.java @@ -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,21 @@ */ @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(); + + if (!(command instanceof HookableCommand)) { return; } // Publish right away, as in the legacy command processing: when the handler fails, its work is rolled back, so // there is no commit to wait for. A hook can also fail after the handler has committed, e.g. when the audit // hook can't store the command. The event then reports the error the API returns, for a change that was saved. - publisher.publishError(hookable, command.getPayload(), error); + publisher.publishError(command, command.getPayload(), ctx.getError()); } } diff --git a/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java index b93083edd0c..7d08b0f36a8 100644 --- a/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/organisation/monetary/command/CurrencyUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CurrencyUpdateCommand extends Command {} +public class CurrencyUpdateCommand extends Command { + + @Override + public String entityName() { + return "CURRENCY"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java index dc6d98a7669..c78afc865f0 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeCreateCommand extends Command {} +public class PaymentTypeCreateCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java index dc251e713ba..49dfd60d02c 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeDeleteCommand extends Command {} +public class PaymentTypeDeleteCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java index 48fdf2b6182..fe60793bbb6 100644 --- a/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java +++ b/fineract-core/src/main/java/org/apache/fineract/portfolio/paymenttype/command/PaymentTypeUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class PaymentTypeUpdateCommand extends Command {} +public class PaymentTypeUpdateCommand extends Command { + + @Override + public String entityName() { + return "PAYMENTTYPE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java b/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java new file mode 100644 index 00000000000..17eacf71677 --- /dev/null +++ b/fineract-core/src/test/java/org/apache/fineract/commands/service/RecoverableCommandErrorClassifierAdapterTest.java @@ -0,0 +1,52 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.commands.service; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verifyNoInteractions; +import static org.mockito.Mockito.when; + +import org.junit.jupiter.api.Test; + +class RecoverableCommandErrorClassifierAdapterTest { + + private final RecoverableErrorClassifier legacy = mock(RecoverableErrorClassifier.class); + + private final RecoverableCommandErrorClassifierAdapter adapter = new RecoverableCommandErrorClassifierAdapter(legacy); + + @Test + void theLegacyRulesDecide() { + var recoverable = new IllegalStateException("recoverable"); + var permanent = new IllegalStateException("permanent"); + + when(legacy.isRecoverable(recoverable)).thenReturn(true); + when(legacy.isRecoverable(permanent)).thenReturn(false); + + assertThat(adapter.isRecoverable(recoverable)).isTrue(); + assertThat(adapter.isRecoverable(permanent)).isFalse(); + } + + @Test + void aFailureTheLegacyRulesCannotClassifyIsNotRecoverable() { + assertThat(adapter.isRecoverable(new Exception("checked"))).isFalse(); + assertThat(adapter.isRecoverable(null)).isFalse(); + verifyNoInteractions(legacy); + } +} diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java index 1415941da4a..7fab6659a80 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookAfterTest.java @@ -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()); @@ -125,10 +126,10 @@ void shouldExposeOfficeAndClientAtTopLevelOfPayload() { @Test void shouldIgnoreCommandThatIsNotHookable() { - final Command command = new Command<>(); + final Command command = new TestPlainCommand(); 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() { @@ -165,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"; } } @@ -186,4 +201,9 @@ private record TestResponse(Long resourceId) { private record TestClientResponse(Long resourceId, Long officeId, Long clientId) { } + + /** The hook takes the context now, so the command and its result are handed over together. */ + private static CommandContext afterContext(Command command, Object response) { + return CommandContext.builder().command(command).response(response).build(); + } } diff --git a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java index af68e2a6f08..4b9a24d0430 100644 --- a/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java +++ b/fineract-core/src/test/java/org/apache/fineract/infrastructure/hooks/command/WebhookCommandHookErrorTest.java @@ -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()); @@ -145,10 +146,10 @@ void shouldPublishImmediatelyInsideEnclosingTransaction() { @Test void shouldIgnoreCommandThatIsNotHookable() { - final Command command = new Command<>(); + final Command command = new TestPlainCommand(); command.setPayload(new TestRequest("contract.pdf", null)); - underTest.onError(command, new IllegalStateException("not found")); + underTest.onError(errorContext(command, new IllegalStateException("not found"))); verifyNoInteractions(eventPublisher, errorHandler); } @@ -158,14 +159,14 @@ void shouldNotMaskCommandErrorWhenPublishingFails() { when(errorHandler.handle(any())).thenReturn(new ErrorInfo(404, 4001, NOT_FOUND_BODY, null)); doThrow(new IllegalStateException("listener failed")).when(eventPublisher).publishEvent(any(HookEvent.class)); - assertDoesNotThrow(() -> underTest.onError(hookableCommand(), new IllegalStateException("not found"))); + assertDoesNotThrow(() -> underTest.onError(errorContext(hookableCommand(), new IllegalStateException("not found")))); } @Test void shouldNotMaskCommandErrorWhenMappingTheErrorFails() { when(errorHandler.handle(any())).thenThrow(new IllegalStateException("no mapper")); - assertDoesNotThrow(() -> underTest.onError(hookableCommand(), new IllegalStateException("not found"))); + assertDoesNotThrow(() -> underTest.onError(errorContext(hookableCommand(), new IllegalStateException("not found")))); verifyNoInteractions(eventPublisher); } @@ -181,19 +182,38 @@ 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"; } } 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-doc/src/docs/en/chapters/architecture/command-audit.adoc b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc new file mode 100644 index 00000000000..e3a4d0dc115 --- /dev/null +++ b/fineract-doc/src/docs/en/chapters/architecture/command-audit.adoc @@ -0,0 +1,144 @@ += Command auditing + +Every command dispatched through the new command processing is recorded in the `m_command` table by the +`fineract-command-audit` module. The record is written before the command runs and updated as it finishes, so a command +that is still in flight, one that completed and one that failed are all distinguishable afterwards. + +Auditing is on as soon as the module is on the classpath. Losing the audit trail should be a decision rather than the +consequence of an unset property. + +[source,properties] +---- +fineract.command.audit.enabled=true +fineract.command.audit.hook-pre-enabled=true +fineract.command.audit.hook-post-enabled=true +fineract.command.audit.hook-error-enabled=true +---- + +NOTE: With auditing switched off, nothing is written to `m_command` at all - and idempotency cannot be used, because it +is these hooks that record how a command finished. See <>. + +== How a command is recorded + +Auditing is implemented as three command hooks, which run after the idempotency hooks: + +[cols="1,1,3"] +|=== +| Hook | State written | When + +| Before +| `UNDER_PROCESSING` +| The command has been accepted and is about to run. + +| After +| `PROCESSED` +| The command returned. Its result is stored, along with `executed_at` and `executed_by_username`. + +| Error +| `ERROR` +| The command threw. The exception message is stored in the `error` column. +|=== + +A command that was never executed - a repeat of an idempotency key, which is answered from the existing record - is not +audited again. The record that owns the key already describes the command, and writing a second one would claim an +execution that never happened. + +== What is stored + +[cols="1,3"] +|=== +| Column | Content + +| `entity_name`, `action_name` +| What the command acted on and what it did, in the vocabulary of `m_permission` - `DOCUMENT`/`CREATE`, +`BUSINESS_DATE`/`UPDATE`. See <>. + +| `state` +| `UNDER_PROCESSING`, `PROCESSED` or `ERROR`. `UNKNOWN` is reported for a key that has no record at all. + +| `request` +| The command's payload, as JSON. + +| `response` +| The result the command produced, as JSON, carrying a type attribute so that it can be read back as the object it was. + +| `error` +| The message of the exception a failed command threw. + +| `initiated_by_username`, `executed_by_username` +| Who asked for the command, and who it ran as. + +| `created_at`, `updated_at`, `executed_at` +| When the record was written, last changed, and when the command ran. + +| `ip_address` +| Where the request came from. + +| `idempotency_key` +| The key the command was claimed under. See the idempotency chapter. + +| `custom_idempotency_distinctor` +| What the key is unique together with, computed when the key was claimed. The empty string when nothing distinguishes +it, including for a command without a key. See the idempotency chapter. + +| `response_status_code` +| Only set for a command that produced no result of its own. See the idempotency chapter. +|=== + +WARNING: `executed_at` and `executed_by_username` are written by the before hook as well as the after hook, so they are +set even for a command that failed or never finished. Read them as "when this record was last worked on" rather than as +proof that the command ran to completion; `state` is what says that. + +== Reliability + +Every write to `m_command` is retried, so that a command is not left recorded in the wrong state because of a deadlock +or a connection dropped mid-flight. A failure is retried when running the same call again could succeed, and never when +it could not - a constraint violation is a verdict, not a mishap, and is excluded explicitly. + +This wider list is set on the command store alone, under `resilience4j.retry.instances.commandStore`. Retrying a write +of the command row is safe because the idempotency key is unique, so a second attempt cannot write it twice. The same +is not true elsewhere: a connection lost during a commit leaves the outcome of that commit unknown, which is why the +jobs that post interest and run close-of-business keep the narrower list they already had. + +If the writes still fail after their attempts are spent, the command itself is unaffected: it has already been +processed and answered. A record that could not be written is logged, and, when the dead-letter queue is enabled, the +command is written to it so that the trail can be reconstructed. + +== Why the names are mandatory + +`Command` declares `entityName()` and `actionName()` as abstract methods, so a command cannot be written without +saying what it acts on. That is deliberate rather than convenient. + +Both names are read by position, not by meaning: the audit search and the checker inbox are defined in terms of them - +the inbox returns "the `actionNames` and `entityNames` the requestor has Checker approval permissions for" - and +maker-checker derives the permission that governs approval by joining them with `_CHECKER`, the way +`PortfolioCommandSourceWritePlatformServiceImpl` does for the legacy processing. The approval columns are already on +this table. A command whose names were missing would be stored with none of that, and would simply not appear in +either view: no error, no failing test, just a row nobody can find. Hence abstract methods and `NOT NULL` columns +rather than an optional interface. + +The names have to match the vocabulary already in `m_permission`, which is not always what the class name suggests - +`CacheSwitchCommand` is `CACHE`/`UPDATE`, not `CACHE`/`SWITCH`, and the entity is `BUSINESS_DATE` rather than +`BUSINESSDATE`. A few commands act on different entities depending on their payload: a note belongs to whatever it is +attached to (`CLIENTNOTE`, `LOANNOTE`, ...) and an image to either `CLIENTIMAGE` or `STAFFIMAGE`, so those compute the +name from the request rather than returning a constant. + +NOTE: Rows written before this column existed are backfilled as `UNKNOWN`. They were recorded when commands did not +carry the names, and saying so is more honest than implying they acted on an entity with an empty name. + +== Relationship with idempotency + +The audit hooks own the lifecycle of the command record. Idempotency claims the key and counts repeats, but it is the +audit hooks that move a command out of `UNDER_PROCESSING` and store what it produced. + +That makes auditing a prerequisite rather than a companion. An application configured with idempotency enabled and +auditing disabled refuses to start, naming the properties that conflict. Were it allowed to run, the first request +under a key would be answered normally, its record would stay `UNDER_PROCESSING` for ever, and every repeat of that key +would be answered `425 Too Early` - a failure that only appears on the second request and never resolves. + +The same holds for the after and error hooks individually: with idempotency enabled, switching off +`fineract.command.audit.hook-post-enabled` or `fineract.command.audit.hook-error-enabled` also refuses to start. The +before hook can be switched off, because claiming the key writes the record it would otherwise write. + +The reverse is fine and is a supported arrangement: auditing without idempotency records every command as usual, reads +no idempotency key, and executes a repeated request again rather than replaying it. diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc index c2f162884f0..739808a91bb 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc @@ -17,7 +17,7 @@ If no idempotency key is assigned to the request, the system will generate one f 2. The system checks there are already executed commands with the same `idempotency key` and `action name` and `entity name` 3. The action based on the result of the check * If the request is completed the system return with the already generated result - * If not completed, return HTTP 409 response + * If not completed, return HTTP 425 response, so the caller knows to come back rather than that something went wrong * If the request is not completed, we process the requests and store the results in the database @@ -32,5 +32,187 @@ In batch requests, you can set the idempotency key for every batch item, in the == Result of the request * When the request is already executed and completed, the system will return a `x-served-from-cache` header with the value `true` in the response and return the original request body. -* When the request is already executed but still not completed, the system will return to HTTP 409 error code +* When the request is already executed but still not completed, the system will return a HTTP 425 Too Early error code * When the request is not executed, the system runs it normally and stores the result in the date + + +== Idempotency in the new command processing + +The new command processing implements idempotency as command hooks, in the `fineract-command-idempotency` module. +It answers a repeated request the same way the legacy processing does - the same `x-served-from-cache` header, the +same `425 Too Early` while the original is still running, the same status and body once it has finished. By default +a key is scoped the way the legacy processing scopes it; see <> for the stricter +alternative. + +=== Configuration + +Idempotency is on as soon as the module is on the classpath; a repeated request quietly executing twice should be a +decision rather than the consequence of an unset property. + +[source,properties] +---- +fineract.command.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true +fineract.command.idempotency.claim-timeout=10m +fineract.command.idempotency.custom-distinctor=ENTITY_NAME_AND_ACTION_NAME +---- + +The key is read from the HTTP header only. It is deliberately not read from a query parameter, because keys in query +strings are copied into access and proxy logs. + +=== How it works + +1. The key is taken from the request header. +2. The command is written to the command store immediately, before it is executed, claiming the key. The claim relies + on a unique constraint, so of several requests arriving at once with the same key exactly one wins and the others + are answered from the store. The command itself can never run twice. +3. The command runs, and the result it produces is stored against the claimed row by the audit hooks. A command that + produces no result of its own - one that failed, whose answer is rendered from an exception - has the answer the + client was sent recorded instead. See <>. + +=== What a repeat is answered from + +A completed command is replayed from the result object it produced. The stored result is read back into the object it +was and handed to the web layer, which renders it with the same serializer that rendered the original answer and +derives the same status code from it. The two answers are identical because they are the same object rendered the same +way, so nothing about the original response has to have been recorded - neither its bytes nor its status. + +A command that produced no result of its own has nothing to hand back. That is the case for a failure, whose answer is +rendered from an exception rather than from a result, and it is the only case where the answer itself is recorded: the +response as it went out, together with the status code it went out with, because a replay of it is thrown rather than +returned and nothing else could say what status to use. `response_status_code` is therefore set for those commands and +empty for every other. + +NOTE: Only a JSON answer can be recorded, because the column holds JSON. An answer of any other kind - a file download, +an empty body - is logged instead of stored, and a repeat of that key is answered with the status and an empty body. + +=== Result of a repeated request + +Every answer served from the command store carries `x-served-from-cache: true`, and no further command record is +written for it: the record that owns the key already describes the command, and a second one would claim an execution +that never happened. + +[cols="1,3"] +|=== +| State of the original command | Answer to the repeat + +| Completed +| The original status code and body. + +| Failed +| The original status code and body, so a repeat of a failure fails exactly as the original did - unless the failure +was recoverable, in which case the repeat is executed again. See <>. + +| Still being processed, claimed within `claim-timeout` +| `425 Too Early`. The original has not finished, so there is nothing to replay yet and the caller should retry. + +| Still being processed, claimed longer ago than `claim-timeout` +| `409 Conflict`, saying the command never finished. With the timeout switched off, `425 Too Early` as above. See +<>. + +| Completed, but its stored result cannot be reconstructed +| `409 Conflict`, saying so. The key has been used and its answer can no longer be produced - reporting a server error +would say the request failed, and an empty body would say it succeeded with nothing to return. Neither is true. Only a +command that completed stores a result, so the command did take effect: it must not be sent again under a new key. + +| Any other state, or a key used for a different request +| `409 Conflict`. +|=== + +=== Scope of an idempotency key + +An idempotency key is unique together with a _distinctor_: a value computed from the command when its key is claimed +and stored beside the key in `m_command.custom_idempotency_distinctor`. The command record is unique on the pair, and a +repeat is matched - and replayed - only against the record with the same key and the same distinctor. +`fineract.command.idempotency.custom-distinctor` chooses how the distinctor is computed: + +[cols="1,2,3"] +|=== +| Value | Distinctor | Scope of a key + +| `ENTITY_NAME_AND_ACTION_NAME` (default) +| `EntityAndActionNameCustomIdempotencyDistinctor`: the command's entity name and action name, as `m_permission` spells +them, joined with `\|` - for example `LOAN\|CREATE`. +| Unique per tenant, entity and action, the way the legacy command processing scopes a key. + +| `NONE` +| `NoCustomIdempotencyDistinctor`: always the empty string. +| Unique per tenant across all commands. +|=== + +An application can replace the distinctor altogether by defining its own `CustomIdempotencyDistinctor` bean. Its value +must be the same for every repeat of a request, must not be `null` and must fit the 255-character column; a value that +does not is refused before the key is claimed. + +IMPORTANT: Under `NONE` the new processing is stricter than the legacy one: the same key sent to two different +endpoints is rejected with `409 Conflict` for the second rather than executed. Clients that derive the key from +something reused across calls, such as a correlation id, then have to send a distinct key per request. + +A repeat is also only replayed when it carries the same request as the original. A key reused for the same endpoint +with a different body is rejected with `409 Conflict` instead of being answered with the earlier result, which would +otherwise report success for something that was never carried out. + +=== Recoverable failures + +Some failures are worth retrying under the same key: a lock that could not be taken, a dependency that was briefly +unavailable. The new command processing treats them as the legacy one does. A failure is recoverable when its +exception is marked `RecoverableError`, or when all of its error codes are listed in the +`idempotency-recoverable-error-codes` global configuration. + +A command that failed recoverably gives its key up: its record is moved to `_RE`, where `` is the +record's own id, and a retry with the original key is executed as a new command. The failure stays on record under the +moved key, together with the answer the client was sent. A key too long to take the suffix is replaced by the first 40 +hex characters of its SHA-256 hash. If the moved key is somehow already taken, or anything else stops the move, the +failure stays under the original key, and a retry is answered with it as for any other failure. + +The rules come from the application through a `RecoverableCommandErrorClassifier` bean; Fineract provides one that +applies the legacy rules. Without one, no failure is recoverable. + +=== Requires auditing + +Claiming a key writes the command record, but the idempotency hooks never write it again: it is the audit hooks that +move a command out of `UNDER_PROCESSING` and store what it produced. Idempotency therefore cannot work without +auditing, and an application configured with idempotency enabled and `fineract.command.audit.enabled=false` refuses to +start rather than failing later in a way that only shows up on a client's second request. + +The same applies to the two audit hooks that record how a command finished, which can be switched off on their own: +with idempotency enabled, `fineract.command.audit.hook-post-enabled=false` (nothing records a completed command) or +`fineract.command.audit.hook-error-enabled=false` (nothing records a failed one) also refuses to start. The before hook +is not required, because claiming the key has already written the record it would write. + +The claim is always stored with the time it was made, which is what <> measures. It is +taken from the timestamp hook when that is on, and from the moment of the claim when it is not. + +Every result type a command handler returns has to be readable back from the store, since a repeat is answered by +reading it back. A test walks every handler on the classpath and fails for a result type Jackson cannot construct, such +as a Lombok `@Builder` class without `@NoArgsConstructor` and `@AllArgsConstructor`. + +See the command auditing chapter for what is recorded and when. + +=== Reliability + +Every write to the command record is retried - claiming the key, recording how the command finished, recording a +repeat, and recording an answer. A claim that loses to contention is tried again; a claim that loses to the unique +constraint is not, because that is the answer rather than a failure, and it means another request already owns the key. + +=== A claim that never finishes + +A command is recorded as `UNDER_PROCESSING` from the moment its key is claimed until the audit hooks record how it +finished. If nothing ever records that - the process dies in between, or the store gives up writing the row after its +retries - the row stays `UNDER_PROCESSING` for good. Answering `425 Too Early` to every repeat would then tell the +caller to come back for an answer that is never coming, and a caller following that advice retries for ever. + +Past `fineract.command.idempotency.claim-timeout`, such a claim is treated as abandoned and a repeat is refused with +`409 Conflict` instead. Nothing distinguishes a command that died from one that is merely slow, so age stands in for +it: set the timeout comfortably above the slowest command rather than tightly, because the cost of being wrong is +telling a caller their request failed while it is still running. + +The timeout is on by default, at 10 minutes. Setting `claim-timeout` to `0` (or leaving it empty) switches it off: an +unfinished claim is then answered `425 Too Early` for as long as it stays unfinished, which is what the legacy command +processing does. A negative value is refused at startup. + +IMPORTANT: The key is refused, not released. The command that claimed it may have reached the database before whatever +stopped it, so running it again is exactly the duplicate this mechanism exists to prevent. Whether the original took +effect has to be established some other way, and a retry needs a new idempotency key. diff --git a/fineract-doc/src/docs/en/chapters/architecture/index.adoc b/fineract-doc/src/docs/en/chapters/architecture/index.adoc index 3ef38dbed7e..99448b1af90 100644 --- a/fineract-doc/src/docs/en/chapters/architecture/index.adoc +++ b/fineract-doc/src/docs/en/chapters/architecture/index.adoc @@ -18,6 +18,8 @@ include::design.adoc[leveloffset=+1] include::persistence.adoc[leveloffset=+1] +include::command-audit.adoc[leveloffset=+1] + include::idempotency.adoc[leveloffset=+1] include::validation.adoc[leveloffset=+1] diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java index face5244f81..6e6f75f9683 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentCreateCommand.java @@ -29,12 +29,12 @@ public class DocumentCreateCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "CREATE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java index ed94119436c..b171d59c900 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentDeleteCommand.java @@ -29,12 +29,12 @@ public class DocumentDeleteCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "DELETE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java index d0c1c7c1b19..a0aba017169 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/DocumentUpdateCommand.java @@ -29,12 +29,12 @@ public class DocumentUpdateCommand extends Command implements HookableCommand { @Override - public String hookEntityName() { + public String entityName() { return "DOCUMENT"; } @Override - public String hookActionName() { + public String actionName() { return "UPDATE"; } } diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java index 2018da75e22..b49730471d1 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageCreateCommand.java @@ -25,4 +25,16 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ImageCreateCommand extends Command {} +public class ImageCreateCommand extends Command { + + /** {@code clients} and {@code staff} are separate permissions, so the entity follows what the request targets. */ + @Override + public String entityName() { + return "staff".equalsIgnoreCase(getPayload().getEntityType()) ? "STAFFIMAGE" : "CLIENTIMAGE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java index e510df6607c..cb7aae60918 100644 --- a/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java +++ b/fineract-document/src/main/java/org/apache/fineract/infrastructure/documentmanagement/command/ImageDeleteCommand.java @@ -25,4 +25,16 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ImageDeleteCommand extends Command {} +public class ImageDeleteCommand extends Command { + + /** {@code clients} and {@code staff} are separate permissions, so the entity follows what the request targets. */ + @Override + public String entityName() { + return "staff".equalsIgnoreCase(getPayload().getEntityType()) ? "STAFFIMAGE" : "CLIENTIMAGE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/dependencies.gradle b/fineract-provider/dependencies.gradle index 8712f19709c..4149e3d09f1 100644 --- a/fineract-provider/dependencies.gradle +++ b/fineract-provider/dependencies.gradle @@ -29,6 +29,7 @@ dependencies { implementation(project(path: ':fineract-command')) implementation(project(path: ':fineract-command-audit')) implementation(project(path: ':fineract-command-jdbc')) + implementation(project(path: ':fineract-command-idempotency')) implementation(project(path: ':fineract-validation')) implementation(project(path: ':fineract-accounting')) implementation(project(path: ':fineract-investor')) diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java new file mode 100644 index 00000000000..881746648a3 --- /dev/null +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/core/jackson3/Jackson3ObjectMapperConfig.java @@ -0,0 +1,67 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import com.fasterxml.jackson.annotation.JsonInclude; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import tools.jackson.databind.DeserializationFeature; +import tools.jackson.databind.MapperFeature; +import tools.jackson.databind.cfg.DateTimeFeature; +import tools.jackson.databind.json.JsonMapper; + +/** + * The application's Jackson 3 mapper, configured to agree with the Jackson 2 one that serves the REST API. + * + *

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

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

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

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

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

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

+ * Masking has to be reapplied because {@code @JsonSerialize(using = MaskedValueSerializer.class)} is a Jackson + * 2 annotation, which Jackson 3 neither sees nor could use the serializer it names. Left alone, a command + * carrying external-service credentials would write them to the command table in the clear. + */ + private static final class LocalDateAndMaskedPropertyModifier extends ValueSerializerModifier { + + private final ValueSerializer localDateAsString = cast( + new FormattedSerializer<>(LocalDate.class, DateTimeFormatter.ISO_LOCAL_DATE)); + private final ValueSerializer localDateAsArray = cast(new LocalDateArraySerializer()); + private final ValueSerializer masked = cast(new MaskedSerializer()); + + @SuppressWarnings("unchecked") + private static ValueSerializer cast(ValueSerializer serializer) { + return (ValueSerializer) serializer; + } + + @Override + public List changeProperties(SerializationConfig config, BeanDescription.Supplier beanDesc, + List beanProperties) { + boolean legacyArrayFormat = beanDesc.getBeanClass().isAnnotationPresent(JsonLocalDateArrayFormat.class); + + for (BeanPropertyWriter writer : beanProperties) { + if (LocalDate.class.equals(writer.getType().getRawClass())) { + writer.assignSerializer(legacyArrayFormat ? localDateAsArray : localDateAsString); + } else if (isMasked(writer)) { + writer.assignSerializer(masked); + } + } + + return beanProperties; + } + + private static boolean isMasked(BeanPropertyWriter writer) { + var annotation = writer.getAnnotation(com.fasterxml.jackson.databind.annotation.JsonSerialize.class); + + return annotation != null && MaskedValueSerializer.class.equals(annotation.using()); + } + } + + private static final class LocalDateArraySerializer extends ValueSerializer { + + @Override + public void serialize(LocalDate value, JsonGenerator gen, SerializationContext context) { + if (value == null) { + gen.writeNull(); + return; + } + gen.writeStartArray(); + gen.writeNumber(value.getYear()); + gen.writeNumber(value.getMonthValue()); + gen.writeNumber(value.getDayOfMonth()); + gen.writeEndArray(); + } + + @Override + public Class handledType() { + return LocalDate.class; + } + } + + private static final class MaskedSerializer extends ValueSerializer { + + @Override + public void serialize(String value, JsonGenerator gen, SerializationContext context) { + gen.writeString(value == null || value.isBlank() ? value : StringUtil.maskValue(value)); + } + + @Override + public Class handledType() { + return String.class; + } + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java index a7c50a88cf8..fd3f12b83c6 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookCreateCommand extends Command {} +public class HookCreateCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java index fe3ce311d9a..043a4d93a0a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookDeleteCommand extends Command {} +public class HookDeleteCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java index 762135f777f..6773b1c30a0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/hooks/command/HookUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class HookUpdateCommand extends Command {} +public class HookUpdateCommand extends Command { + + @Override + public String entityName() { + return "HOOK"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java index be114d1164d..f0188e21f97 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffCreateCommand extends Command {} +public class StaffCreateCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java index 62cb6557753..d58cfbf3a4e 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffUpdateCommand extends Command {} +public class StaffUpdateCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java index 20ce42e06e2..e4790b6f477 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/staff/command/StaffUploadCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class StaffUploadCommand extends Command {} +public class StaffUploadCommand extends Command { + + @Override + public String entityName() { + return "STAFF"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java index d9fb6693165..8deae856725 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/command/WorkingDaysUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class WorkingDaysUpdateCommand extends Command {} +public class WorkingDaysUpdateCommand extends Command { + + @Override + public String entityName() { + return "WORKINGDAYS"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java index 2528d818f8e..71db6ca9fd3 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java +++ b/fineract-provider/src/main/java/org/apache/fineract/organisation/workingdays/handler/UpdateWorkingDaysCommandHandler.java @@ -18,6 +18,7 @@ */ package org.apache.fineract.organisation.workingdays.handler; +import io.github.resilience4j.retry.annotation.Retry; import java.util.Collections; import java.util.Map; import lombok.RequiredArgsConstructor; @@ -37,6 +38,7 @@ public class UpdateWorkingDaysCommandHandler implements CommandHandler command) { @@ -52,4 +54,8 @@ public WorkingDaysUpdateResponse handle(Command comman .extendTermForRepaymentsOnHolidays(request.getExtendTermForRepaymentsOnHolidays()).build(); } + @Override + public WorkingDaysUpdateResponse fallback(Command command, Throwable t) { + return CommandHandler.super.fallback(command, t); + } } diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java index a4cb599276a..20246624114 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralCreateCommand extends Command {} +public class ClientCollateralCreateCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java index eba27f6e03b..2ce0e8455bc 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralDeleteCommand extends Command {} +public class ClientCollateralDeleteCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java index feb29e65491..6eaf24a64ba 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/ClientCollateralUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ClientCollateralUpdateCommand extends Command {} +public class ClientCollateralUpdateCommand extends Command { + + @Override + public String entityName() { + return "CLIENT_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java index 1adf4b6179e..bf40a5f07ee 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductCreateCommand extends Command {} +public class CollateralProductCreateCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java index 1d6fa91e5c9..4258ef4b3a9 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductDeleteCommand extends Command {} +public class CollateralProductDeleteCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java index facbeba45ea..ef1b22fea84 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/CollateralProductUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class CollateralProductUpdateCommand extends Command {} +public class CollateralProductUpdateCommand extends Command { + + @Override + public String entityName() { + return "COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java index f592c359fff..9fee66bf235 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/command/LoanCollateralDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class LoanCollateralDeleteCommand extends Command {} +public class LoanCollateralDeleteCommand extends Command { + + @Override + public String entityName() { + return "LOAN_COLLATERAL_PRODUCT"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java index aadf3498a09..2f9c12e0fe8 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralCreateResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralCreateResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java index 5422ea7bf1c..5bd70d065ad 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java index dd0ea35389e..8e4da26359a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/ClientCollateralUpdateResponse.java @@ -21,11 +21,15 @@ import java.io.Serial; import java.io.Serializable; import java.math.BigDecimal; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class ClientCollateralUpdateResponse implements Serializable { @Serial @@ -39,6 +43,8 @@ public class ClientCollateralUpdateResponse implements Serializable { @Data @Builder + @NoArgsConstructor + @AllArgsConstructor public static class Changes implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java index f6f087c2698..5835dc6b823 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductCreateResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductCreateResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java index e7df5b7580c..2d919008aef 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java index 2ab854b1dc9..f466f4ffe65 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/CollateralProductUpdateResponse.java @@ -22,11 +22,15 @@ import java.io.Serial; import java.io.Serializable; import java.math.BigDecimal; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class CollateralProductUpdateResponse implements Serializable { @Serial @@ -38,6 +42,8 @@ public class CollateralProductUpdateResponse implements Serializable { @Data @Builder + @NoArgsConstructor + @AllArgsConstructor @Schema(name = "CollateralProductUpdateChanges") public static class Changes implements Serializable { diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java index 78c6cdaa742..52e00e02d36 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/collateralmanagement/data/LoanCollateralDeleteResponse.java @@ -20,11 +20,15 @@ import java.io.Serial; import java.io.Serializable; +import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; +import lombok.NoArgsConstructor; @Data @Builder +@NoArgsConstructor +@AllArgsConstructor public class LoanCollateralDeleteResponse implements Serializable { @Serial diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java index a0a72c6168d..a6c9cdd2ced 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartCreateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartCreateCommand extends Command {} +public class InterestRateChartCreateCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java index 1486c0a6f84..6763673ba09 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartDeleteCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartDeleteCommand extends Command {} +public class InterestRateChartDeleteCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java index 5b3cdde0057..47f75a1a89a 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsCreateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsCreateCommand extends Command {} +public class InterestRateChartSlabsCreateCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java index fb62d9f9c50..36fd33e05c0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsDeleteCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsDeleteCommand extends Command {} +public class InterestRateChartSlabsDeleteCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java index 5d4905b8684..403593e462e 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartSlabsUpdateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartSlabsUpdateCommand extends Command {} +public class InterestRateChartSlabsUpdateCommand extends Command { + + @Override + public String entityName() { + return "CHARTSLAB"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java index ceab67450b8..efb3c3bc838 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/interestratechart/command/InterestRateChartUpdateCommand.java @@ -26,4 +26,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class InterestRateChartUpdateCommand extends Command {} +public class InterestRateChartUpdateCommand extends Command { + + @Override + public String entityName() { + return "INTERESTRATECHART"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java index f64ab37fb1c..43a25d8dcb4 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixCreateCommand extends Command {} +public class ProductMixCreateCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java index b5174548afd..04319d9fc8f 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixDeleteCommand extends Command {} +public class ProductMixDeleteCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java index c9c1241484f..d177f290ffd 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/loanproduct/productmix/command/ProductMixUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class ProductMixUpdateCommand extends Command {} +public class ProductMixUpdateCommand extends Command { + + @Override + public String entityName() { + return "PRODUCTMIX"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java index 2df5e965c39..b84d71f95f9 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingAttendanceUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingAttendanceUpdateCommand extends Command {} +public class MeetingAttendanceUpdateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "SAVEORUPDATEATTENDANCE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java index 69af8608c0c..f3b4718931d 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingCreateCommand extends Command {} +public class MeetingCreateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java index 861a13ede03..e3cb4904b52 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingDeleteCommand extends Command {} +public class MeetingDeleteCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java index 13cf54c743f..a2e46a6e86b 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/meeting/command/MeetingUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class MeetingUpdateCommand extends Command {} +public class MeetingUpdateCommand extends Command { + + @Override + public String entityName() { + return "MEETING"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java index 22061079144..1f21ec305f0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteCreateCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteCreateCommand extends Command {} +public class NoteCreateCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java index ba97ea2f6a4..4250030d343 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteDeleteCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteDeleteCommand extends Command {} +public class NoteDeleteCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java index 2671bb2f92c..a126b8cf8c0 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/note/command/NoteUpdateCommand.java @@ -25,4 +25,23 @@ @Data @EqualsAndHashCode(callSuper = true) -public class NoteUpdateCommand extends Command {} +public class NoteUpdateCommand extends Command { + + /** A note is governed by the permission of whatever it is attached to, not by one note permission. */ + @Override + public String entityName() { + return switch (getPayload().getType()) { + case CLIENT -> "CLIENTNOTE"; + case GROUP -> "GROUPNOTE"; + case LOAN -> "LOANNOTE"; + case LOAN_TRANSACTION -> "LOANTRANSACTIONNOTE"; + case SAVING_ACCOUNT, SAVINGS_TRANSACTION -> "SAVINGNOTE"; + case SHARE_ACCOUNT -> "SHARENOTE"; + }; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java index f4fd467dd7a..06780c079b3 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateCreateCommand extends Command {} +public class TemplateCreateCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java index 8d8f328c752..f7be73f4e4d 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateDeleteCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateDeleteCommand extends Command {} +public class TemplateDeleteCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "DELETE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java index eecf7933c2a..bb420d05225 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/command/TemplateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class TemplateUpdateCommand extends Command {} +public class TemplateUpdateCommand extends Command { + + @Override + public String entityName() { + return "TEMPLATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java b/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java index 520245966c2..10f774d35ea 100644 --- a/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java +++ b/fineract-provider/src/main/java/org/apache/fineract/template/service/TemplateDomainServiceImpl.java @@ -21,7 +21,6 @@ import java.util.List; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; import org.apache.fineract.template.data.TemplateCreateRequest; import org.apache.fineract.template.data.TemplateCreateResponse; import org.apache.fineract.template.data.TemplateData; @@ -47,8 +46,6 @@ @ConditionalOnMissingBean(value = TemplateDomainService.class, ignored = TemplateDomainServiceImpl.class) public class TemplateDomainServiceImpl implements TemplateDomainService { - private final CommandMapper commandMapper; - private final TemplateRepository templateRepository; private final TemplateMapper templateMapper; private final TemplateMapperDataMapper templateMapperDataMapper; diff --git a/fineract-provider/src/main/resources/application.properties b/fineract-provider/src/main/resources/application.properties index 5367286a464..430aa2ea6fa 100644 --- a/fineract-provider/src/main/resources/application.properties +++ b/fineract-provider/src/main/resources/application.properties @@ -590,6 +590,8 @@ fineract.retry.instances.inlineCob.wait-duration=${FINERACT_INLINE_COB_RETRY_WAI fineract.retry.instances.inlineCob.enable-exponential-backoff=${FINERACT_INLINE_COB_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} fineract.retry.instances.inlineCob.exponential-backoff-multiplier=${FINERACT_INLINE_COB_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} + + resilience4j.retry.instances.processJobDetailForExecution.max-attempts=${FINERACT_PROCESS_JOB_DETAIL_RETRY_MAX_ATTEMPTS:3} resilience4j.retry.instances.processJobDetailForExecution.wait-duration=${FINERACT_PROCESS_JOB_DETAIL_RETRY_WAIT_DURATION:1s} resilience4j.retry.instances.processJobDetailForExecution.enable-exponential-backoff=${FINERACT_PROCESS_JOB_DETAIL_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} @@ -615,6 +617,11 @@ resilience4j.retry.instances.commandBusinessDateUpdate.wait-duration=${FINERACT_ resilience4j.retry.instances.commandBusinessDateUpdate.enable-exponential-backoff=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} resilience4j.retry.instances.commandBusinessDateUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} resilience4j.retry.instances.commandBusinessDateUpdate.retryExceptions=${FINERACT_COMMAND_BUSINESS_DATE_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} +resilience4j.retry.instances.commandWorkingDaysUpdate.max-attempts=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_MAX_ATTEMPTS:3} +resilience4j.retry.instances.commandWorkingDaysUpdate.wait-duration=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_WAIT_DURATION:1s} +resilience4j.retry.instances.commandWorkingDaysUpdate.enable-exponential-backoff=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} +resilience4j.retry.instances.commandWorkingDaysUpdate.exponential-backoff-multiplier=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} +resilience4j.retry.instances.commandWorkingDaysUpdate.retryExceptions=${FINERACT_COMMAND_WORKING_DAYS_UPDATE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} # cache @@ -899,15 +906,14 @@ fineract.command.jdbc.enabled=${FINERACT_COMMAND_JDBC_ENABLED:true} fineract.command.jdbc.file-dead-letter-queue-enabled=${FINERACT_COMMAND_JDBC_FILE_DEAD_LETTER_QUEUE_ENABLED:false} fineract.command.jdbc.file-dead-letter-queue-path=${FINERACT_COMMAND_JDBC_FILE_DEAD_LETTER_QUEUE_PATH:/tmp/fineract/dlq} fineract.command.audit.enabled=${FINERACT_COMMAND_AUDIT_ENABLED:true} -fineract.command.hooks.audit-pre=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE:true} -fineract.command.hooks.audit-post=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST:true} -fineract.command.hooks.audit-error=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR:true} -fineract.command.hooks.servlet-header-pre=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_PRE:true} -fineract.command.hooks.timestamp-pre=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_PRE:true} -fineract.command.hooks.username-pre=${FINERACT_COMMAND_PROCESSORS_USERNAME_PRE:true} +fineract.command.audit.hook-pre-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_PRE_ENABLED:true} +fineract.command.audit.hook-post-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED:true} +fineract.command.audit.hook-error-enabled=${FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR_ENABLED:true} +fineract.command.hook-servlet-headers-enabled=${FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_ENABLED:true} +fineract.command.hook-timestamp-enabled=${FINERACT_COMMAND_PROCESSORS_TIMESTAMP_ENABLED:true} +fineract.command.hook-username-enabled=${FINERACT_COMMAND_PROCESSORS_USERNAME_ENABLED:true} # TODO: move to separate module # this is duplicated on purpose to keep fineract-command independent; once all modules are migrated we clean up -fineract.command.idempotency-key-header-name=${FINERACT_IDEMPOTENCY_KEY_HEADER_NAME:Idempotency-Key} # command store @@ -915,7 +921,13 @@ resilience4j.retry.instances.commandStore.max-attempts=${FINERACT_COMMAND_STORE_ resilience4j.retry.instances.commandStore.wait-duration=${FINERACT_COMMAND_STORE_RETRY_WAIT_DURATION:1s} resilience4j.retry.instances.commandStore.enable-exponential-backoff=${FINERACT_COMMAND_STORE_RETRY_ENABLE_EXPONENTIAL_BACKOFF:true} resilience4j.retry.instances.commandStore.exponential-backoff-multiplier=${FINERACT_COMMAND_STORE_RETRY_EXPONENTIAL_BACKOFF_MULTIPLIER:2} -resilience4j.retry.instances.commandStore.retryExceptions=${FINERACT_COMMAND_STORE_RETRY_EXCEPTIONS:org.springframework.dao.ConcurrencyFailureException,org.eclipse.persistence.exceptions.OptimisticLockException,jakarta.persistence.OptimisticLockException,org.springframework.orm.jpa.JpaOptimisticLockingFailureException} +# The command row is written on the idempotency path, where a deadlock or a connection dropped mid-flight +# is a reason to try again rather than to give up: retrying cannot write the row twice, because the key is +# unique. A constraint violation is the opposite - the row is already there - and is ignored explicitly so +# that widening the list later cannot start retrying it by accident. Deliberately only this instance: the +# COB and interest jobs must not retry on a connection lost during commit, where the outcome is unknown. +resilience4j.retry.instances.commandStore.retryExceptions=${FINERACT_COMMAND_STORE_RETRY_EXCEPTIONS:org.springframework.dao.TransientDataAccessException,org.springframework.dao.RecoverableDataAccessException,java.sql.SQLTransientException,java.sql.SQLRecoverableException,jakarta.persistence.OptimisticLockException,jakarta.persistence.PessimisticLockException,jakarta.persistence.LockTimeoutException,jakarta.persistence.QueryTimeoutException,org.eclipse.persistence.exceptions.OptimisticLockException} +resilience4j.retry.instances.commandStore.ignoreExceptions=${FINERACT_COMMAND_STORE_RETRY_IGNORE_EXCEPTIONS:org.springframework.dao.DataIntegrityViolationException,jakarta.persistence.EntityExistsException} # Retry for the lookups every request needs before it can run (tenant and business dates), so a short database outage # or a connection pool timeout does not fail the request. Each attempt can wait for the pool connection timeout. @@ -936,5 +948,23 @@ resilience4j.retry.instances.tenantContextLookup.retryExceptions=${FINERACT_TENA # fineract.command.disruptor.ring-buffer-size=${FINERACT_COMMAND_RING_BUFFER_SIZE:1024} # fineract.command.disruptor.producer-type=${FINERACT_COMMAND_PRODUCER_TYPE:single} +# command idempotency + +fineract.command.idempotency.enabled=${FINERACT_COMMAND_IDEMPOTENCY_ENABLED:true} +# note: keep environment variable name for backwards compatibility +fineract.command.idempotency.key-header-name=${FINERACT_IDEMPOTENCY_KEY_HEADER_NAME:Idempotency-Key} +fineract.command.idempotency.hook-key-header-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_KEY_HEADER_PRE:true} +fineract.command.idempotency.hook-check-pre=${FINERACT_COMMAND_IDEMPOTENCY_HOOK_CHECK_PRE:true} +# How long a claimed command may stay unfinished before a repeat of its key is refused rather than told to retry. +# Guards against a claim that is never resolved - the process died before recording the outcome - which would +# otherwise answer 425 for ever. The key is never re-executed, only refused, so set it comfortably above the +# slowest command rather than tightly. 0 (or empty) switches the timeout off and answers 425 for as long as the claim +# stays unfinished, as the legacy command processing does. +fineract.command.idempotency.claim-timeout=${FINERACT_COMMAND_IDEMPOTENCY_CLAIM_TIMEOUT:10m} +# What an idempotency key is unique together with. ENTITY_NAME_AND_ACTION_NAME (default): the command's entity and +# action names joined with "|" (for example LOAN|CREATE), so a key may be used once per entity and action, the way the +# legacy command processing scopes it. NONE: nothing, so a key is unique per tenant across all commands. +fineract.command.idempotency.custom-distinctor=${FINERACT_COMMAND_IDEMPOTENCY_CUSTOM_DISTINCTOR:ENTITY_NAME_AND_ACTION_NAME} + # Fineract Default Config values fineract.defaults.office-id=${FINERACT_CONFIG_DEFAULT_OFFICE_ID:1} diff --git a/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java new file mode 100644 index 00000000000..bbfa0745573 --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerResultRehydrationTest.java @@ -0,0 +1,194 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; +import static org.assertj.core.api.Assertions.assertThat; + +import com.fasterxml.jackson.annotation.JsonProperty; +import java.lang.reflect.Field; +import java.lang.reflect.Modifier; +import java.lang.reflect.ParameterizedType; +import java.lang.reflect.Type; +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import org.apache.fineract.command.core.CommandHandler; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; +import org.apache.fineract.infrastructure.core.jackson3.Jackson3ObjectMapperConfig; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.config.BeanDefinition; +import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider; +import org.springframework.core.ResolvableType; +import org.springframework.core.type.filter.AssignableTypeFilter; +import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.node.ObjectNode; +import tools.jackson.databind.node.StringNode; + +/** + * Holds every command handler's result to being readable back from the command store. + * + *

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

+ * This walks every {@link CommandHandler} on the classpath, builds a stored row for its result type with every nested + * object present, and reads it back through the mapper the command store uses. + */ +class CommandHandlerResultRehydrationTest { + + /** The sample handlers that exist to exercise the framework; they are not commands the application serves. */ + private static final String SAMPLE_HANDLERS = "org.apache.fineract.command.test"; + + private static final String FINERACT_PACKAGE = "org.apache.fineract"; + + private final ObjectMapper mapper = new Jackson3ObjectMapperConfig().jackson3ObjectMapper(); + + private final JsonCommandMapper commandJsonMapper = new JsonCommandMapper(mapper); + + @Test + void everyCommandResultCanBeReadBackForAReplay() { + var unreadable = new ArrayList(); + + for (Class handler : commandHandlers()) { + if (handler.getName().startsWith(SAMPLE_HANDLERS)) { + continue; + } + + var result = ResolvableType.forClass(handler).as(CommandHandler.class).getGeneric(1).resolve(); + + if (result == null || Void.class.equals(result)) { + continue; + } + + var stored = storedRow(result, new HashSet<>()); + + stored.set(COMMAND_JSON_CLASS_ATTRIBUTE, new StringNode(result.getCanonicalName())); + + try { + assertThat((Object) commandJsonMapper.map(stored)).isInstanceOf(result); + } catch (RuntimeException | AssertionError e) { + unreadable.add(handler.getSimpleName() + " -> " + result.getSimpleName() + ": " + rootMessage(e)); + } + } + + assertThat(unreadable).as("These command results cannot be read back from the command store, so a repeat of the request is " + + "refused with 409 instead of being given its answer. Give the type, and every type nested in it, a " + + "constructor Jackson can use - for a Lombok @Builder that means adding @NoArgsConstructor and " + "@AllArgsConstructor.") + .isEmpty(); + } + + /** + * A stored row with every nested Fineract type present as an object, so that each one has to be constructed too. + * Scalars are left out: they never need a constructor, and their formats are covered by the wire-format tests. + */ + private ObjectNode storedRow(Class type, Set> visiting) { + var node = mapper.createObjectNode(); + + if (!visiting.add(type)) { + return node; + } + + for (var current = type; current != null && !Object.class.equals(current); current = current.getSuperclass()) { + for (Field field : current.getDeclaredFields()) { + if (Modifier.isStatic(field.getModifiers()) || field.isSynthetic()) { + continue; + } + + var name = propertyName(field); + var nested = nestedType(field.getType()); + + if (nested != null) { + node.set(name, storedRow(nested, visiting)); + } else if (Collection.class.isAssignableFrom(field.getType())) { + var element = nestedType(elementType(field.getGenericType())); + + if (element != null) { + node.putArray(name).add(storedRow(element, visiting)); + } + } + } + } + + visiting.remove(type); + + return node; + } + + private static String propertyName(Field field) { + var property = field.getAnnotation(JsonProperty.class); + + return property != null && !property.value().isEmpty() ? property.value() : field.getName(); + } + + private static Class nestedType(Class type) { + if (type == null || type.isEnum() || type.isInterface() || type.isPrimitive() || !type.getName().startsWith(FINERACT_PACKAGE)) { + return null; + } + + return type; + } + + private static Class elementType(Type type) { + if (type instanceof ParameterizedType parameterized && parameterized.getActualTypeArguments().length == 1 + && parameterized.getActualTypeArguments()[0] instanceof Class element) { + return element; + } + + return null; + } + + private static String rootMessage(Throwable t) { + var root = t; + + while (root.getCause() != null) { + root = root.getCause(); + } + + var message = root.getMessage(); + + return message == null ? root.getClass().getSimpleName() : message.lines().findFirst().orElse(message); + } + + private static List> commandHandlers() { + var scanner = new ClassPathScanningCandidateComponentProvider(false); + + scanner.addIncludeFilter(new AssignableTypeFilter(CommandHandler.class)); + + var found = new ArrayList>(); + + for (BeanDefinition definition : scanner.findCandidateComponents(FINERACT_PACKAGE)) { + try { + found.add(Class.forName(definition.getBeanClassName())); + } catch (ClassNotFoundException e) { + throw new IllegalStateException("Scanned a handler that cannot be loaded: " + definition.getBeanClassName(), e); + } + } + + assertThat(found).as("The scan must actually find the handlers, or this test passes by finding nothing.").isNotEmpty(); + + return found; + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java new file mode 100644 index 00000000000..baabf1138da --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/command/CommandHandlerRetryCoverageTest.java @@ -0,0 +1,98 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.command; + +import static org.assertj.core.api.Assertions.assertThat; + +import io.github.resilience4j.retry.annotation.Retry; +import java.lang.reflect.Method; +import java.util.ArrayList; +import java.util.List; +import org.apache.fineract.command.core.CommandHandler; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.config.BeanDefinition; +import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider; +import org.springframework.core.type.filter.AssignableTypeFilter; + +/** + * Holds every command handler to the retry policy, so that executing a command is as resilient as recording it. + * + *

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

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

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

+ * The end-to-end suite covers the Spring MVC counterpart; Fineract itself serves its API through Jersey, which is this. + */ +class IdempotencyCommandExceptionMapperJerseyTest { + + private static final String STORED_ANSWER = """ + {"developerMessage":"The request was invalid.","httpStatusCode":"400","errors":[{"parameterName":"principal",\ + "defaultUserMessage":"The parameter principal cannot be blank.","value":null}],"amount":1.50}"""; + + private ApplicationHandler handler; + + @BeforeEach + void startJersey() { + // built here rather than in a field, because standing a Jersey application up can fail and a constructor that + // throws is a finding of its own + handler = new ApplicationHandler(resourceConfig()); + } + + /** + * Jersey's Spring bridge is on the classpath and looks for a context of its own; an empty one keeps it satisfied + * without dragging an application context into a test about how bytes reach the wire. + */ + private static ResourceConfig resourceConfig() { + var springContext = new AnnotationConfigApplicationContext(); + + springContext.refresh(); + + return new ResourceConfig().property("contextConfig", springContext).register(IdempotencyCommandExceptionMapper.class) + .register(ReplayResource.class); + } + + @Test + void aReplayedFailureIsWrittenAsTheDocumentItIsRatherThanAsAQuotedString() throws Exception { + var body = new ByteArrayOutputStream(); + + var response = handler.apply(request("/failed"), body).get(); + + assertEquals(400, response.getStatus(), "A repeat of a failure must answer with the status it was first answered with."); + assertEquals("true", response.getStringHeaders().getFirst(IDEMPOTENT_CACHE_HEADER), + "A replay must tell the client it was served from the command store."); + assertEquals(STORED_ANSWER, body.toString(UTF_8), + "The client must receive the stored answer byte for byte, not a JSON string containing it."); + } + + @Test + void aFailureWithNothingStoredAnswersWithItsStatusAndAnEmptyBody() throws Exception { + var body = new ByteArrayOutputStream(); + + var response = handler.apply(request("/nothing-stored"), body).get(); + + assertEquals(500, response.getStatus(), "An inconsistent record answers 500 rather than nothing at all."); + assertEquals("", body.toString(UTF_8), "There is nothing to replay, so the body is empty rather than \"null\"."); + } + + private static ContainerRequest request(String path) { + return new ContainerRequest(URI.create("http://localhost/"), URI.create("http://localhost" + path), "GET", null, + new MapPropertiesDelegate(), null); + } + + @Path("/") + public static class ReplayResource { + + @GET + @Path("failed") + public String failed() { + throw new CommandIdempotencyFailedException("a-key", 400, STORED_ANSWER); + } + + @GET + @Path("nothing-stored") + public String nothingStored() { + throw new CommandIdempotencyFailedException("a-key", null, null); + } + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java new file mode 100644 index 00000000000..d6f5d49206c --- /dev/null +++ b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/core/jackson3/CommandReplayRehydrationTest.java @@ -0,0 +1,146 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.fineract.infrastructure.core.jackson3; + +import static org.apache.fineract.command.core.CommandConstants.COMMAND_JSON_CLASS_ATTRIBUTE; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.databind.DeserializationFeature; +import com.fasterxml.jackson.databind.JsonDeserializer; +import com.fasterxml.jackson.databind.JsonSerializer; +import com.fasterxml.jackson.databind.MapperFeature; +import java.util.ArrayList; +import java.util.List; +import org.apache.fineract.command.jdbc.store.mapping.JsonCommandMapper; +import org.apache.fineract.infrastructure.core.jersey.converter.DateJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.ExternalIdJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.JsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.LocalTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.converter.OffsetDateTimeJsonConverter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonDeserializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.JacksonSerializerAdapter; +import org.apache.fineract.infrastructure.core.jersey.serializer.legacy.JacksonLocalDateArrayModule; +import org.junit.jupiter.api.Test; +import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder; +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.ObjectMapper; + +/** + * Walks a command result through the replay path exactly as production does, and checks the client cannot tell. + * + *

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

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

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

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

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

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

+ * These strings are not a specification anyone wrote down; they are what the application has always sent, and clients + * have been built against them. Every value below was captured from the running mapper rather than reasoned out, so a + * failure here means the wire format moved — which is a breaking change for every caller, whatever caused it. + */ +public class JacksonWireFormatCharacterizationTest { + + private final ObjectMapper mapper = webObjectMapper(); + + /** Built exactly as {@link JerseyJacksonConverterConfig} builds the mapper Jersey serialises responses with. */ + private static ObjectMapper webObjectMapper() { + List> converters = List.of(new LocalDateTimeJsonConverter(), new OffsetDateTimeJsonConverter(), + new LocalTimeJsonConverter(), new DateJsonConverter(), new ExternalIdJsonConverter()); + + List> serializers = new ArrayList<>(converters.stream().map(JacksonSerializerAdapter::new).toList()); + List> deserializers = new ArrayList<>(converters.stream().map(JacksonDeserializerAdapter::new).toList()); + + ObjectMapper objectMapper = new Jackson2ObjectMapperBuilder() // + .serializers(serializers.toArray(new JsonSerializer[0])) // + .serializationInclusion(JsonInclude.Include.NON_NULL) // + .deserializers(deserializers.toArray(new JsonDeserializer[0])) // + .featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // + .featuresToEnable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS) // + .build(); + + objectMapper.registerModule(new JacksonLocalDateArrayModule()); + + return objectMapper; + } + + @Test + void everyHandledTypeSerialisesToItsEstablishedShape() throws Exception { + assertEquals(""" + {"text":"hello","flag":true,"count":7,"reference":9223372036854775807,\ + "amount":1.50,"precise":12345678901234567890.12345678901,"status":"ACTIVE",\ + "localDate":"2026-10-05","localDateTime":"2026-10-05T11:22:33.123456789",\ + "offsetDateTime":"2026-10-05T11:22:33.123456789Z","localTime":"11:22:33.123456789",\ + "date":"2026-10-05T11:22:33Z","externalId":"ext-1","secret":"s*******alue",\ + "nested":{"text":"inner","localDate":"2026-01-02"},"dates":[[2026,1,2],[2026,1,3]]}""", + mapper.writeValueAsString(populated()), "The JSON the API produces must not change."); + // note the asymmetry: a LocalDate property is written as a string, but a List is written as arrays, + // because the serializer modifier only reassigns properties whose raw type is LocalDate. Clients depend on + // both shapes as they are. + } + + @Test + void nullsAreOmittedRatherThanWritten() throws Exception { + assertEquals("{\"text\":\"only\"}", mapper.writeValueAsString(Everything.builderOfText("only")), + "Null properties are left out of responses; writing them would change every payload."); + } + + @Test + void aBeanMarkedLegacyKeepsTheArrayShapeForLocalDate() throws Exception { + assertEquals("{\"text\":\"legacy\",\"localDate\":[2026,10,5]}", + mapper.writeValueAsString(new Legacy("legacy", LocalDate.of(2026, 10, 5))), + "Beans marked for the legacy format must keep writing LocalDate as a [year, month, day] array."); + } + + @Test + void whatTheApiAcceptsIsUnchanged() throws Exception { + var parsed = mapper.readValue(""" + {"text":"hello","localDate":"2026-10-05","localDateTime":"2026-10-05T11:22:33.123456789",\ + "offsetDateTime":"2026-10-05T11:22:33.123456789Z","localTime":"11:22:33.123456789",\ + "date":"2026-10-05T11:22:33Z","externalId":"ext-1","amount":1.50,"unknown":"ignored"}""", Everything.class); + + assertEquals("hello", parsed.getText()); + assertEquals(LocalDate.of(2026, 10, 5), parsed.getLocalDate()); + assertEquals(LocalDateTime.parse("2026-10-05T11:22:33.123456789"), parsed.getLocalDateTime()); + assertEquals(OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z"), parsed.getOffsetDateTime()); + assertEquals(LocalTime.parse("11:22:33.123456789"), parsed.getLocalTime()); + assertEquals("ext-1", parsed.getExternalId().getValue()); + assertEquals(new BigDecimal("1.50"), parsed.getAmount(), "A decimal must keep its scale when read."); + assertNull(parsed.getStatus(), "An absent property stays null."); + } + + @Test + void anUnknownPropertyIsIgnoredRatherThanRejected() throws Exception { + assertEquals("hello", mapper.readValue("{\"text\":\"hello\",\"nope\":1}", Everything.class).getText()); + } + + @Test + void anEnumIsAcceptedWhateverItsCase() throws Exception { + assertEquals(Status.ACTIVE, mapper.readValue("{\"status\":\"active\"}", Everything.class).getStatus()); + } + + public static Everything populated() { + var nested = new Nested("inner", LocalDate.of(2026, 1, 2)); + + return new Everything("hello", true, 7, Long.MAX_VALUE, new BigDecimal("1.50"), new BigDecimal("12345678901234567890.12345678901"), + Status.ACTIVE, LocalDate.of(2026, 10, 5), LocalDateTime.parse("2026-10-05T11:22:33.123456789"), + OffsetDateTime.parse("2026-10-05T11:22:33.123456789Z"), LocalTime.parse("11:22:33.123456789"), + Date.from(java.time.Instant.parse("2026-10-05T11:22:33Z")), new ExternalId("ext-1"), "secret-value", nested, + List.of(LocalDate.of(2026, 1, 2), LocalDate.of(2026, 1, 3))); + } + + public enum Status { + ACTIVE, CLOSED + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class Everything { + + private String text; + private Boolean flag; + private Integer count; + private Long reference; + private BigDecimal amount; + private BigDecimal precise; + private Status status; + private LocalDate localDate; + private LocalDateTime localDateTime; + private OffsetDateTime offsetDateTime; + private LocalTime localTime; + private Date date; + private ExternalId externalId; + @JsonSerialize(using = MaskedValueSerializer.class) + private String secret; + private Nested nested; + private List dates; + + public static Everything builderOfText(String text) { + var everything = new Everything(); + + everything.setText(text); + + return everything; + } + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + public static class Nested { + + private String text; + private LocalDate localDate; + } + + @Data + @NoArgsConstructor + @AllArgsConstructor + @JsonLocalDateArrayFormat + public static class Legacy { + + private String text; + private LocalDate localDate; + } +} diff --git a/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java b/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java index beae8b6aced..92c1020452e 100644 --- a/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java +++ b/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateDomainServiceImplTest.java @@ -22,7 +22,6 @@ import static org.mockito.Mockito.when; import java.util.List; -import org.apache.fineract.command.jdbc.store.mapping.CommandMapper; import org.apache.fineract.template.data.TemplateData; import org.apache.fineract.template.data.TemplateMapperData; import org.apache.fineract.template.domain.Template; @@ -40,9 +39,6 @@ @ExtendWith(MockitoExtension.class) class TemplateDomainServiceImplTest { - @Mock - private CommandMapper commandMapper; - @Mock private TemplateRepository templateRepository; diff --git a/fineract-provider/src/test/resources/application-test.properties b/fineract-provider/src/test/resources/application-test.properties index 929985f8259..662a2ee90ae 100644 --- a/fineract-provider/src/test/resources/application-test.properties +++ b/fineract-provider/src/test/resources/application-test.properties @@ -362,9 +362,13 @@ 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.idempotency.enabled=true +fineract.command.idempotency.key-header-name=Idempotency-Key +fineract.command.idempotency.hook-key-header-pre=true +fineract.command.idempotency.hook-check-pre=true +fineract.command.hook-servlet-headers-enabled=true +fineract.command.hook-timestamp-enabled=true +fineract.command.hook-username-enabled=true diff --git a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java index 0a75f1ef512..e763b552876 100644 --- a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java +++ b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateCreateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class FloatingRateCreateCommand extends Command {} +public class FloatingRateCreateCommand extends Command { + + @Override + public String entityName() { + return "FLOATINGRATE"; + } + + @Override + public String actionName() { + return "CREATE"; + } +} diff --git a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java index 944ecc0c0f0..98e4a319c67 100644 --- a/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java +++ b/fineract-rates/src/main/java/org/apache/fineract/portfolio/floatingrates/command/FloatingRateUpdateCommand.java @@ -25,4 +25,15 @@ @Data @EqualsAndHashCode(callSuper = true) -public class FloatingRateUpdateCommand extends Command {} +public class FloatingRateUpdateCommand extends Command { + + @Override + public String entityName() { + return "FLOATINGRATE"; + } + + @Override + public String actionName() { + return "UPDATE"; + } +} diff --git a/settings.gradle b/settings.gradle index 17e3ea136d6..24685d79748 100644 --- a/settings.gradle +++ b/settings.gradle @@ -65,6 +65,7 @@ include ':fineract-command-jdbc' include ':fineract-command-audit' include ':fineract-command-async' include ':fineract-command-disruptor' +include ':fineract-command-idempotency' include ':fineract-accounting' include ':fineract-provider' include ':fineract-branch'