Light, fluffy, and always free - The AWS Local Emulator alternative
fix(lifecycle): run shutdown hooks before HTTP server stops (#431) (#519)
TiM6f12f782015c
diff --git a/docs/configuration/initialization-hooks.md b/docs/configuration/initialization-hooks.mdindex 8a0b011203..c762d7ecd0 100644--- a/docs/configuration/initialization-hooks.md+++ b/docs/configuration/initialization-hooks.md@@ -6,7 +6,7 @@ environment (creating buckets, populating data, configuring resources, etc.) orHook scripts ending with `.sh` are discovered in the following directories:- **Startup hooks** (`/etc/floci/init/start.d`) run after the HTTP server is ready and accepting connections on port 4566. This means hooks can safely make HTTP calls back to Floci (e.g. using the AWS CLI).-- **Shutdown hooks** (`/etc/floci/init/stop.d`) run when Floci is shutting down, after `destroy()` is triggered.+- **Shutdown hooks** (`/etc/floci/init/stop.d`) run during the pre-shutdown phase, while the HTTP server is still accepting connections, so hooks can make HTTP calls back to Floci (e.g. using the AWS CLI). The server only stops once all shutdown hooks have completed.If a hook directory does not exist or contains no `.sh` scripts, Floci skips it and continues normally.If the hook path exists but is not a directory, it is ignored.@@ -111,6 +111,12 @@ aws --endpoint-url http://localhost:4566 \This example assumes the script is stored at `/etc/floci/init/stop.d/01-cleanup-parameter.sh`.It removes the parameter during shutdown to leave the environment clean.+!!! note "Shutdown timing"+ Shutdown hooks run before the HTTP server stops, so Floci's total shutdown time+ grows by the cumulative runtime of all stop hooks. Make sure external orchestrator+ grace periods accommodate this (e.g. Kubernetes `terminationGracePeriodSeconds`,+ Docker Compose `stop_grace_period`).+## ConfigurationYou can customize hook behavior via configuration:diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.javaindex fb8dcdd99d..1548629cd5 100644--- a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java@@ -10,6 +10,7 @@ import io.github.hectorvent.floci.services.elasticache.proxy.ElastiCacheProxyManimport io.github.hectorvent.floci.services.rds.container.RdsContainerManager;import io.github.hectorvent.floci.services.rds.proxy.RdsProxyManager;import io.quarkus.runtime.Quarkus;+import io.quarkus.runtime.ShutdownDelayInitiatedEvent;import io.quarkus.runtime.ShutdownEvent;import io.quarkus.runtime.StartupEvent;import io.quarkus.vertx.http.HttpServerStart;@@ -83,23 +84,29 @@ public class EmulatorLifecycle {}}- void onStop(@Observes ShutdownEvent ignored) throws IOException, InterruptedException {+ void onPreShutdown(@Observes ShutdownDelayInitiatedEvent ignored) {LOG.info("=== AWS Local Emulator Shutting Down ===");+ // Log-and-continue for every failure mode. Resource cleanup in onStop() must still run,+ // and cleanup routines (proxy/container/storage shutdown) must not see an interrupted+ // thread, so we intentionally do NOT restore the interrupt flag here.try {initializationHooksRunner.run(InitializationHook.STOP);- } catch (IOException | InterruptedException e) {+ } catch (InterruptedException e) {+ LOG.error("Shutdown hook execution interrupted", e);+ } catch (IOException e) {LOG.error("Shutdown hook execution failed", e);- throw e;} catch (RuntimeException e) {LOG.error("Shutdown hook script failed", e);- } finally {- elastiCacheProxyManager.stopAll();- rdsProxyManager.stopAll();- elastiCacheContainerManager.stopAll();- rdsContainerManager.stopAll();- storageFactory.shutdownAll();}+ }++ void onStop(@Observes ShutdownEvent ignored) {+ elastiCacheProxyManager.stopAll();+ rdsProxyManager.stopAll();+ elastiCacheContainerManager.stopAll();+ rdsContainerManager.stopAll();+ storageFactory.shutdownAll();LOG.info("=== AWS Local Emulator Stopped ===");}diff --git a/src/main/resources/application.yml b/src/main/resources/application.ymlindex 3bb8cfae0d..fac0a3e4fe 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -4,6 +4,10 @@ quarkus:host: 0.0.0.0limits:max-body-size: ${floci.max-request-size}M+ shutdown:+ # Enables the pre-shutdown phase so stop hooks run before the HTTP server stops.+ # No 'delay' value is set - observers run synchronously, no artificial sleep is introduced.+ delay-enabled: truenative:additional-build-args: >---initialize-at-run-time=org.apache.hc.client5.http.impl.auth.NTLMEngineImpl,diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycleTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycleTest.javaindex c624ac47cb..b6b4653a24 100644--- a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycleTest.java+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycleTest.java@@ -9,6 +9,8 @@ import io.github.hectorvent.floci.services.elasticache.container.ElastiCacheContimport io.github.hectorvent.floci.services.elasticache.proxy.ElastiCacheProxyManager;import io.github.hectorvent.floci.services.rds.container.RdsContainerManager;import io.github.hectorvent.floci.services.rds.proxy.RdsProxyManager;+import io.quarkus.runtime.ShutdownDelayInitiatedEvent;+import io.quarkus.runtime.ShutdownEvent;import io.quarkus.runtime.StartupEvent;import org.junit.jupiter.api.BeforeEach;import org.junit.jupiter.api.DisplayName;@@ -20,6 +22,7 @@ import org.mockito.junit.jupiter.MockitoExtension;import java.io.IOException;+import static org.mockito.Mockito.doThrow;import static org.mockito.Mockito.never;import static org.mockito.Mockito.verify;import static org.mockito.Mockito.when;@@ -41,18 +44,22 @@ class EmulatorLifecycleTest {@BeforeEachvoid setUp() {- when(config.storage()).thenReturn(storageConfig);- when(storageConfig.mode()).thenReturn("in-memory");- when(storageConfig.persistentPath()).thenReturn("/app/data");emulatorLifecycle = new EmulatorLifecycle(storageFactory, serviceRegistry, config,elastiCacheContainerManager, elastiCacheProxyManager,rdsContainerManager, rdsProxyManager, initializationHooksRunner);}+ private void stubStorageConfig() {+ when(config.storage()).thenReturn(storageConfig);+ when(storageConfig.mode()).thenReturn("in-memory");+ when(storageConfig.persistentPath()).thenReturn("/app/data");+ }+@Test@DisplayName("Should log Ready immediately when no startup hooks exist")void shouldLogReadyImmediatelyWhenNoHooksExist() throws IOException, InterruptedException {+ stubStorageConfig();when(initializationHooksRunner.hasHooks(InitializationHook.START)).thenReturn(false);emulatorLifecycle.onStart(Mockito.mock(StartupEvent.class));@@ -65,6 +72,7 @@ class EmulatorLifecycleTest {@Test@DisplayName("Should defer hook execution when startup hooks exist")void shouldDeferHookExecutionWhenHooksExist() throws IOException, InterruptedException {+ stubStorageConfig();when(initializationHooksRunner.hasHooks(InitializationHook.START)).thenReturn(true);emulatorLifecycle.onStart(Mockito.mock(StartupEvent.class));@@ -74,4 +82,84 @@ class EmulatorLifecycleTest {// run() is NOT called synchronously — it will be called by the virtual threadverify(initializationHooksRunner, never()).run(InitializationHook.START);}++ @Test+ @DisplayName("Should run shutdown hooks in the pre-shutdown phase, before the HTTP server stops")+ void shouldRunShutdownHooksInPreShutdownPhase() throws IOException, InterruptedException {+ emulatorLifecycle.onPreShutdown(Mockito.mock(ShutdownDelayInitiatedEvent.class));++ verify(initializationHooksRunner).run(InitializationHook.STOP);+ // Resource cleanup must NOT happen in pre-shutdown; it belongs to ShutdownEvent.+ verify(storageFactory, never()).shutdownAll();+ verify(elastiCacheProxyManager, never()).stopAll();+ verify(rdsProxyManager, never()).stopAll();+ }++ @Test+ @DisplayName("Should swallow RuntimeException from shutdown hook scripts")+ void shouldSwallowRuntimeExceptionFromShutdownHook() throws IOException, InterruptedException {+ doThrow(new IllegalStateException("boom")).when(initializationHooksRunner).run(InitializationHook.STOP);++ emulatorLifecycle.onPreShutdown(Mockito.mock(ShutdownDelayInitiatedEvent.class));++ verify(initializationHooksRunner).run(InitializationHook.STOP);+ }++ @Test+ @DisplayName("Should swallow IOException from shutdown hook scripts so resource cleanup still runs")+ void shouldSwallowIOExceptionFromShutdownHook() throws IOException, InterruptedException {+ doThrow(new IOException("io")).when(initializationHooksRunner).run(InitializationHook.STOP);++ emulatorLifecycle.onPreShutdown(Mockito.mock(ShutdownDelayInitiatedEvent.class));++ verify(initializationHooksRunner).run(InitializationHook.STOP);+ }++ @Test+ @DisplayName("Should swallow InterruptedException from shutdown hooks without poisoning cleanup thread")+ void shouldSwallowInterruptedExceptionWithoutPropagatingInterrupt() throws IOException, InterruptedException {+ doThrow(new InterruptedException("interrupted")).when(initializationHooksRunner).run(InitializationHook.STOP);++ Thread.interrupted();+ try {+ emulatorLifecycle.onPreShutdown(Mockito.mock(ShutdownDelayInitiatedEvent.class));+ // The thread must NOT be left interrupted: ShutdownEvent cleanup runs next and+ // interruptible I/O inside stopAll()/shutdownAll() would short-circuit otherwise.+ org.junit.jupiter.api.Assertions.assertFalse(Thread.currentThread().isInterrupted(),+ "Interrupt flag must not leak into ShutdownEvent cleanup");+ } finally {+ Thread.interrupted();+ }+ verify(initializationHooksRunner).run(InitializationHook.STOP);+ }++ @Test+ @DisplayName("Should clean up resources on ShutdownEvent without running hooks again")+ void shouldCleanUpResourcesOnShutdownWithoutRunningHooks() throws IOException, InterruptedException {+ emulatorLifecycle.onStop(Mockito.mock(ShutdownEvent.class));++ verify(elastiCacheProxyManager).stopAll();+ verify(rdsProxyManager).stopAll();+ verify(elastiCacheContainerManager).stopAll();+ verify(rdsContainerManager).stopAll();+ verify(storageFactory).shutdownAll();+ // Hooks are handled by onPreShutdown, never from ShutdownEvent.+ verify(initializationHooksRunner, never()).run(InitializationHook.STOP);+ }++ @Test+ @DisplayName("Should still run full resource cleanup when a pre-shutdown hook fails")+ void shouldRunFullCleanupAfterFailingPreShutdownHook() throws IOException, InterruptedException {+ doThrow(new IOException("hook blew up")).when(initializationHooksRunner).run(InitializationHook.STOP);++ emulatorLifecycle.onPreShutdown(Mockito.mock(ShutdownDelayInitiatedEvent.class));+ emulatorLifecycle.onStop(Mockito.mock(ShutdownEvent.class));++ verify(initializationHooksRunner).run(InitializationHook.STOP);+ verify(elastiCacheProxyManager).stopAll();+ verify(rdsProxyManager).stopAll();+ verify(elastiCacheContainerManager).stopAll();+ verify(rdsContainerManager).stopAll();+ verify(storageFactory).shutdownAll();+ }}