AuthEmailExecutorConfiguration.java
/*
* Copyright (c) 2007-2026 MetaSolutions AB
*
* Licensed 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.entrystore.rest.springboot.configuration;
import lombok.extern.slf4j.Slf4j;
import org.entrystore.rest.springboot.util.HttpUtil;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import java.util.concurrent.ThreadPoolExecutor;
/**
* Executors for the asynchronous part of the password-reset and sign-up flows (token generation, password
* hashing, SMTP send). {@code AuthService.pwReset} and {@code AuthService.signup} move that work off the request
* thread so the answer takes as long whether or not the address has an account (password reset: unknown,
* disabled or active; sign-up: new or existing), closing a timing-based account-enumeration side channel. Each
* flow has its own executor, so a flood of one cannot fill the queue of the other.
*/
@Slf4j
@Configuration
public class AuthEmailExecutorConfiguration {
private static final int POOL_SIZE = 2;
private static final int QUEUE_CAPACITY = 100;
private static final int DRAIN_SECONDS = 30;
@Bean
ThreadPoolTaskExecutor passwordResetTaskExecutor() {
return authEmailExecutor("password-reset-async-", "password-reset");
}
@Bean
ThreadPoolTaskExecutor signupTaskExecutor() {
return authEmailExecutor("signup-async-", "sign-up");
}
/**
* A queued mail dispatch with its recipient, so that a dispatch dropped on shutdown is logged with its address.
* {@code toString} omits the recipient, which is not sanitized: the rejection message of a full queue names the
* task.
*/
public record QueuedDispatch(String recipient, Runnable dispatch) implements Runnable {
@Override
public void run() {
dispatch.run();
}
@Override
public String toString() {
return "QueuedDispatch";
}
}
/**
* Builds one flow's executor.
* <p>
* Pool size is intentionally small: each flow's throughput is bounded by its rate limiter
* ({@code PasswordResetRateLimiter}, {@code SignupRateLimiter}), so two threads are enough to absorb
* concurrent dispatches without blocking the request path. Threads are daemons so a shutdown that misses the
* container callback still does not block JVM exit.
* <p>
* The queue is bounded to cap heap growth under distributed credential-stuffing or an SMTP outage: at queue
* saturation {@code execute} throws {@code TaskRejectedException} (a
* {@link java.util.concurrent.RejectedExecutionException}), which {@code AuthService.submitDispatch} catches
* and treats as a client-silent drop — the response stays at the generic 200 so the timing-equivalence guarantee is preserved, but the rejection is logged at ERROR and
* increments the {@code auth.pwreset.rejected} or {@code auth.signup.rejected} Micrometer counter so operators
* can alert on sustained drops via monitoring rather than log scraping. A {@code CallerRunsPolicy} would have
* run the rejected task on the request thread, which re-opens the timing oracle this executor exists to close.
* <p>
* Declared as beans so the container owns their lifecycle: {@code afterPropertiesSet()} calls
* {@code initialize()} on startup, and on context close the executor is shut down as described below,
* discarding the queued backlog and awaiting the already-running tasks for {@value #DRAIN_SECONDS} seconds.
* The await is best-effort: {@code shutdownNow()} has already interrupted the workers at that point — an
* in-flight SMTP send usually still completes only because a blocking socket write does not respond to
* interruption.
* <p>
* Discarding rather than draining is deliberate, and takes both flags below to actually happen.
* {@code waitForTasksToCompleteOnShutdown} stays off so {@code shutdown()} takes the {@code shutdownNow()}
* branch. {@code acceptTasksAfterContextClose} is on because without it the two workers keep draining the
* queue through the coordinated {@code SmartLifecycle} stop phase, blocking context close on the lifecycle
* latch for up to {@code timeoutPerShutdownPhase} (30s) before {@code destroy()} finally discards the rest:
* {@code ThreadPoolTaskExecutor}'s {@code initiateEarlyShutdown()} is a no-op unless
* {@code strictEarlyShutdown} is set, and {@code markShutdown()} defeats the {@code beforeExecute} pause guard,
* so nothing actually stops the workers during that phase. With the flag set the executor skips the stop phase
* entirely and {@code destroy()} → {@code shutdownNow()} is the first and only shutdown step. Its side effect —
* dispatches submitted during the close window are still accepted, then dropped — is harmless here: Boot's
* graceful shutdown stops the connector before bean destruction, and a client-silent drop is the contract
* anyway.
* <p>
* Draining the queue instead would not terminate — two workers against the 5s SMTP timeouts clear roughly a
* dozen sends in {@value #DRAIN_SECONDS} seconds, so a queue anywhere near {@value #QUEUE_CAPACITY} cannot
* finish, and on timeout Spring only logs a warning without following up with {@code shutdownNow()}. Those
* tasks would then keep running past context close, storing tokens in a cache the restart is about to discard
* and mailing links that are already dead. Dropping a queued dispatch is the outcome the submit methods already
* accept on rejection; {@code cancelRemainingTask} logs each one, with the address {@code AuthService} queues in a
* {@link QueuedDispatch}, so the drop is not silent.
* <p>
* {@code newThread} is overridden to install an {@code UncaughtExceptionHandler}:
* {@code AuthService.dispatchConfirmationMail} deliberately runs the hashing and {@code putToken} outside its
* try/catch (nothing needs cleaning up before the token is stored), and relies on this handler to make a
* {@code Throwable} from that stretch reach the logs instead of being swallowed by {@code ThreadPoolExecutor}'s
* default {@code Worker.run} path. That depends on the task being handed to {@code execute()}, as
* {@code AuthService.submitDispatch} does — a {@code submit()} would capture the same {@code Throwable} into the
* returned {@code Future}, where the handler never fires.
*/
static ThreadPoolTaskExecutor authEmailExecutor(String threadNamePrefix, String flow) {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor() {
@Override
public Thread newThread(Runnable runnable) {
Thread thread = super.newThread(runnable);
thread.setUncaughtExceptionHandler((t, ex) ->
log.error("Uncaught error in {} worker {}", flow, t.getName(), ex));
return thread;
}
@Override
protected void cancelRemainingTask(Runnable task) {
String recipient = task instanceof QueuedDispatch queued
? HttpUtil.sanitizeForLog(queued.recipient()) : "an unknown address";
log.warn("Dropping queued {} dispatch for {} on shutdown; the user must request it again", flow,
recipient);
super.cancelRemainingTask(task);
}
};
executor.setCorePoolSize(POOL_SIZE);
executor.setMaxPoolSize(POOL_SIZE);
executor.setQueueCapacity(QUEUE_CAPACITY);
executor.setThreadNamePrefix(threadNamePrefix);
executor.setDaemon(true);
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy());
executor.setAcceptTasksAfterContextClose(true);
executor.setAwaitTerminationSeconds(DRAIN_SECONDS);
return executor;
}
}