Skip to content

FINERACT-2485: Pass a CommandContext to command hooks (step 1/9) - #6907

Open
adamsaghy wants to merge 1 commit into
apache:developfrom
adamsaghy:FINERACT-2485/step-1-command-context
Open

adamsaghy wants to merge 1 commit into
apache:developfrom
adamsaghy:FINERACT-2485/step-1-command-context

Conversation

@adamsaghy

@adamsaghy adamsaghy commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Step 1 of 9 of FINERACT-2485 — splitting #6871 into reviewable pieces. Merge in step order.

Based on develop; this is the first step.

What this step does

Command hooks receive a CommandContext (command, response, error, state) instead of separate arguments. A before hook can mark the command as handled (skipExecution) so the dispatcher returns a response the hook supplied, and can stop the remaining hooks (skipHooks). The synchronous, async and disruptor dispatchers all honour it; the disruptor dispatcher also hands each command a fresh future before publishing its slot.

  • Each command module gets constants for its properties; hook switches move under their module: fineract.command.audit.hook-pre|post|error-enabled, fineract.command.hook-servlet-headers|timestamp|username-enabled.
  • The audit module reports at startup which of its hooks are on (AuditCommandPropertyCheck).
  • The JDBC store types are renamed (JdbcCommandRepository, JdbcCommandMapper, JsonCommandMapper) and the store takes a CommandContext. CommandStore is reduced to store(CommandContext): its lookups had no callers, and step 5 adds the ones idempotency uses.
  • The webhook command hooks (fineract-core) are adapted to the new interface.

Behaviour is otherwise unchanged: the idempotency key header is still read and recorded, as on develop.

This carries the hook and module refactoring from #6231 by Aleksandar Vidakovic (credited as co-author).

Upgrade notes

  • Hook switches renamed. The properties move from fineract.command.hooks.* to fineract.command.audit.hook-pre|post|error-enabled and fineract.command.hook-servlet-headers|timestamp|username-enabled. The environment variables get an _ENABLED suffix, e.g. FINERACT_COMMAND_PROCESSORS_AUDIT_POST → FINERACT_COMMAND_PROCESSORS_AUDIT_POST_ENABLED, and ..._SERVLET_HEADER_PRE → ..._SERVLET_HEADERS_ENABLED. The 1.16.x variables are still read as a fallback when the new one is unset. Setting the old property names directly no longer has any effect. All hooks default to enabled.
  • Auditing is on by default in fineract-command-audit. fineract.command.audit.enabled and the three audit hook switches default to true (matchIfMissing = true), and so do the three core hooks. fineract-provider sets these explicitly, so a Fineract deployment is unaffected. An application that embeds fineract-command-audit without setting the property now audits, and needs a CommandStore bean (e.g. fineract-command-jdbc) or fineract.command.audit.enabled=false to start.

Verified

fineract-command, -jdbc, -audit, -async, -disruptor builds with tests; fineract-core webhook hook tests; fineract-provider command and template tests; checkstyle and spotless. Not verified on a running Fineract instance.

Stack

  1. FINERACT-2485: Pass a CommandContext to command hooks (step 1/9) #6907 Pass a CommandContext to command hooks ← this PR
  2. FINERACT-2485: Make the Jackson 3 mapper agree with the Jersey wire format (step 2/9) #6908 Make the Jackson 3 mapper agree with the Jersey wire format
  3. FINERACT-2485: Retry every command handler (step 3/9) #6909 Retry every command handler
  4. FINERACT-2485: Record what a command acted on and what it did (step 4/9) #6910 Record what a command acted on and what it did
  5. FINERACT-2485: Claim idempotency keys in the command store (step 5/9) #6911 Claim idempotency keys in the command store
  6. FINERACT-2485: Make every command result readable from the command store (step 6/9) #6912 Make every command result readable from the command store
  7. FINERACT-2485: Add idempotency to the new command processing (step 7/9) #6913 Add idempotency to the new command processing
  8. FINERACT-2485: Refuse a repeat whose claim never finished (step 8/9) #6914 Refuse a repeat whose claim never finished
  9. FINERACT-2485: Release the idempotency key of a recoverably failed command (step 9/9) #6915 Release the idempotency key of a recoverably failed command

Umbrella and history: #6871.

@Aman-Mittal Aman-Mittal left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the whole diff against develop at feb1ba4. The refactor itself is behaviour-preserving on every path that executes today, and all 94 checks are green — blocked is the review gate, not a failure. Comments inline; summarising what I think needs an answer before this lands, since eight more PRs stack on it.

Config, worth fixing here

  • application.properties:905 has FINERACT_COMMAND_PROCESSORS_SERVLET_HEADER_ENABLED (singular) where the test properties and the description say ..._SERVLET_HEADERS_ENABLED. The provider file wins at runtime, so the documented switch doesn't exist.
  • The old hook property and env var names shipped in 1.16.0 and 1.16.1, and the new dispatcher is live on released endpoints. An operator who had set FINERACT_COMMAND_PROCESSORS_AUDIT_ERROR=false gets the hook back silently. A nested fallback or an upgrade note would cover it.
  • CommandProperties declares the three core hooks true while their @ConditionalOnProperty has no matchIfMissing, so an unset property means the hook isn't registered. The javadoc you added to AuditCommandProperties describes this exact trap, and the audit hooks did get matchIfMissing.

Contract questions the stack depends on

  • skipExecution/skipHooks have no tests — 12 grep hits, all production. Given steps 7-9 build on them, coverage in all three dispatchers seems worth having now.
  • AuditCommandHookError guards on skipExecution; AuditCommandHookBefore doesn't. On a replay that means a second row under the same idempotency key, and since idempotency_key carries only a plain index, the symptom is findOneByIdempotencyKey throwing IncorrectResultSizeDataAccessException from then on rather than a constraint error.
  • checkRequestInstanceByKey reads getResponse(). Unused today, so nothing catches it; steps 6-9 will.
  • ctx is created outside the returned Supplier, so it's now single-use. Every caller invokes it once, so it's latent — but it's an unstated constraint on CommandDispatcher.

Checked, no action needed — @Builder.Default does survive Lombok's no-args constructor (verified on 1.18.46), so the new properties.getTimeout() can't NPE; the four removed CommandStore methods had no callers on develop; @InheritInverseConfiguration resolves unambiguously to the single-source map(Command<?>); the @Retry fallback signature tracks correctly; hooks.adoc includes the interfaces by line range so the docs follow the signature change; and dropping the unused CommandMapper from TemplateDomainServiceImpl is a genuine cleanup. On the disruptor change — publishing in finally is the right idiom and shouldn't be "fixed" into the try, since an unpublished claimed sequence stalls the ring buffer permanently; the new comment explaining why the future is handed back before publication is the kind of thing I wish more of this module had.

Nothing here is an objection to the approach — handing hooks a context instead of positional arguments is clearly the right shape, and splitting #6871 into nine reviewable steps made this reviewable at all.

@Aman-Mittal Aman-Mittal left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some comments from my side

Command hooks now receive a CommandContext - the command, its response, its error and its
state - instead of separate arguments, so a before hook can mark a command as handled
(skipExecution) and have the dispatcher return a response it supplied, and can stop the
remaining hooks (skipHooks). The synchronous, async and disruptor dispatchers all honour it;
the disruptor dispatcher hands each command a fresh future before publishing its slot.

Each command module gets constants for its properties, and the hook switches move under the
module they belong to (fineract.command.audit.hook-*-enabled,
fineract.command.hook-*-enabled). The audit module reports at startup which of its hooks are
on. The JDBC store is renamed to its Jdbc*/Json* types and stores a CommandContext. The
webhook command hooks are adapted to the new hook interface.

Step 1 of 9 of FINERACT-2485.

Co-authored-by: Aleksandar Vidakovic <aleks@apache.org>
@adamsaghy
adamsaghy force-pushed the FINERACT-2485/step-1-command-context branch from 5dbfd53 to fee7367 Compare November 14, 2026 16:54
@Aman-Mittal

Copy link
Copy Markdown
Member

Re-reviewed on fee7367c. Every one of the eleven threads is addressed, and I checked each against the code rather than the reply. All resolved.

What I verified:

  • The env var is now ..._SERVLET_HEADERS_ENABLED, and all six switches chain the 1.16.x name as a fallback. I checked each fallback against the names actually in the 1.16.1 application.properties: _AUDIT_PRE, _AUDIT_POST, _AUDIT_ERROR, _SERVLET_HEADER_PRE, _TIMESTAMP_PRE, _USERNAME_PRE. They match, so an upgraded deployment keeps the hooks it switched off.
  • The three core hooks have matchIfMissing = true, and CommandProperties carries the same note as AuditCommandProperties about keeping the two in step.
  • CommandStore is down to store(CommandContext). The method I asked about is gone rather than fixed, which is the better answer.
  • AuditCommandHookBefore and WebhookCommandHookError both guard on skipExecution, and DefaultCommandHookManager clears skipHooks in a finally. Between them the refused-duplicate path in FINERACT-2485: Add idempotency to the new command processing (step 7/9) #6913 no longer depends on hook ordering or on a flag surviving a throw, which was the thing I was most worried about across the stack.
  • SynchronousCommandDispatcher builds the context inside the lambda, and CommandDispatcher#dispatch states the call-once constraint.
  • The async dispatcher unwraps CompletionException before setError, so all three dispatchers hand hooks the exception the handler threw.
  • CommandHookManager is CommandContext<?, ?> with the raw types confined to the implementation.

The new tests are the ones I asked for plus two I had not thought of: skipExecutionWithoutSkipHooksStillRunsTheRemainingBeforeHooks and skipHooksStopsTheErrorPhaseLikeAnyOther pin the cases where the semantics could drift later, which is where this will matter once steps 7 to 9 are in.

Two points you answered rather than changed, both reasonably, recorded here so they are not re-litigated later: keeping the startup failure when audit is on with no CommandStore instead of degrading to @ConditionalOnBean, and keeping the PROCESSORS prefix rather than carrying a second set of old names. Agreed on both.

CI is green on this head, 95 checks. Nothing further from me on this step.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants