Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(lifecycle): add support for startup and shutdown initialization hooks (#128)

Cyril Schumacher7b2576fb42e5
diff --git a/docker-compose.yml b/docker-compose.yml
index f1fc09a0be..f24a3fee73 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,21 +1,23 @@
-services:
- floci:
- build:
- context: .
- dockerfile: Dockerfile.native
- ports:
- - "4566:4566"
- - "6379-6399:6379-6399"
- - "7001-7099:7001-7099"
- volumes:
- - /var/run/docker.sock:/var/run/docker.sock
- environment:
- FLOCI_SERVICES_DOCKER_NETWORK: floci_default
- FLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"
- FLOCI_STORAGE_PERSISTENT_PATH: /app/data
- networks:
- default:
- aliases:
- - localhost.floci.cloud
-
-
+services:
+ floci:
+ build:
+ context: .
+ dockerfile: Dockerfile.native
+ ports:
+ - "4566:4566"
+ - "6379-6399:6379-6399"
+ - "7001-7099:7001-7099"
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ - ./scripts:/etc/floci/init/start.d
+ - ./scripts:/etc/floci/init/stop.d
+ environment:
+ FLOCI_SERVICES_DOCKER_NETWORK: floci_default
+ FLOCI_SERVICES_RDS_PROXY_BASE_PORT: "7001"
+ FLOCI_STORAGE_PERSISTENT_PATH: /app/data
+ networks:
+ default:
+ aliases:
+ - localhost.floci.cloud
+
+
diff --git a/docs/configuration/application-yml.md b/docs/configuration/application-yml.md
index 47a5f07e9e..a4e3807ee7 100644
--- a/docs/configuration/application-yml.md
+++ b/docs/configuration/application-yml.md
@@ -15,6 +15,11 @@ floci:
validate-signatures: false # Set to true to enforce AWS request signing
presign-secret: local-emulator-secret # HMAC secret for S3 pre-signed URL verification
+ init-hooks:
+ shell-executable: /bin/bash
+ timeout-seconds: 30
+ shutdown-grace-period-seconds: 2
+
storage:
mode: memory # memory | persistent | hybrid | wal
persistent-path: ./data
diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.md
index a1df467a68..4809f0254a 100644
--- a/docs/configuration/docker-compose.md
+++ b/docs/configuration/docker-compose.md
@@ -12,6 +12,8 @@ services:
- "4566:4566"
volumes:
- ./data:/app/data
+ - ./init/start.d:/etc/floci/init/start.d:ro
+ - ./init/stop.d:/etc/floci/init/stop.d:ro
```
## Full Setup (with ElastiCache and RDS)
@@ -38,6 +40,23 @@ services:
!!! warning "Docker socket"
Lambda, ElastiCache, and RDS require access to the Docker socket (`/var/run/docker.sock`) to spawn and manage containers. If you don't use these services, you can omit that volume.
+## Initialization Hooks
+
+Hook scripts can be mounted into the container to run custom setup and teardown logic:
+
+```yaml
+services:
+ floci:
+ image: hectorvent/floci:latest
+ ports:
+ - "4566:4566"
+ volumes:
+ - ./init/start.d:/etc/floci/init/start.d:ro
+ - ./init/stop.d:/etc/floci/init/stop.d:ro
+```
+
+See [`initialization-hooks.md`](./initialization-hooks.md) for execution behavior and configuration details.
+
## Persistence
By default Floci stores all data in memory — data is lost on restart. To persist data to disk, set the storage path and enable persistent mode:
@@ -98,4 +117,4 @@ steps:
AWS_ACCESS_KEY_ID: test
AWS_SECRET_ACCESS_KEY: test
run: mvn test
-```
\ No newline at end of file
+```
diff --git a/docs/configuration/initialization-hooks.md b/docs/configuration/initialization-hooks.md
new file mode 100644
index 0000000000..a8bc3fa853
--- /dev/null
+++ b/docs/configuration/initialization-hooks.md
@@ -0,0 +1,47 @@
+# Initialization Hooks
+
+Floci can execute shell scripts during startup and shutdown.
+
+## Directories
+
+- Startup hooks are loaded from `/etc/floci/init/start.d`
+- Shutdown hooks are loaded from `/etc/floci/init/stop.d`
+
+Only files ending with `.sh` are executed.
+
+## Execution Model
+
+- Scripts are executed in lexicographical order
+- Hook scripts are executed sequentially
+- Hook execution is fail-fast: execution stops at the first script that fails or times out
+
+## Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `floci.init-hooks.shell-executable` | `/bin/bash` | Shell executable used to run hook scripts |
+| `floci.init-hooks.timeout-seconds` | `30` | Maximum execution time per hook script before it is considered failed |
+| `floci.init-hooks.shutdown-grace-period-seconds` | `2` | Time to wait after `destroy()` before forcing process termination |
+
+### Example
+
+```yaml
+floci:
+ init-hooks:
+ shell-executable: /bin/bash
+ timeout-seconds: 30
+ shutdown-grace-period-seconds: 2
+```
+
+## Docker Compose Example
+
+```yaml
+services:
+ floci:
+ image: hectorvent/floci:latest
+ ports:
+ - "4566:4566"
+ volumes:
+ - ./init/start.d:/etc/floci/init/start.d:ro
+ - ./init/stop.d:/etc/floci/init/stop.d:ro
+```
diff --git a/pom.xml b/pom.xml
index abc258d1cb..6f8c01aa3f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -108,6 +108,11 @@
<artifactId>quarkus-junit5</artifactId>
<scope>test</scope>
</dependency>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-junit5-mockito</artifactId>
+ <scope>test</scope>
+ </dependency>
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
index 4ab2a1c970..89f25264e3 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -47,6 +47,8 @@ public interface EmulatorConfig {
ServicesConfig services();
+ InitHooksConfig initHooks();
+
interface StorageConfig {
@WithDefault("hybrid")
String mode();
@@ -381,4 +383,15 @@ public interface EmulatorConfig {
/** Docker network to attach Lambda containers to. Empty = default bridge. */
Optional<String> dockerNetwork();
}
-}
\ No newline at end of file
+
+ interface InitHooksConfig {
+ @WithDefault("/bin/bash")
+ String shellExecutable();
+
+ @WithDefault("2")
+ long shutdownGracePeriodSeconds();
+
+ @WithDefault("30")
+ long timeoutSeconds();
+ }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java
index 6b6a3144bd..13fb7fbdc6 100644
--- a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java
+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java
@@ -3,8 +3,9 @@ package io.github.hectorvent.floci.lifecycle;
import io.github.hectorvent.floci.config.EmulatorConfig;
import io.github.hectorvent.floci.core.common.ServiceRegistry;
import io.github.hectorvent.floci.core.storage.StorageFactory;
+import io.github.hectorvent.floci.lifecycle.inithook.InitializationHook;
+import io.github.hectorvent.floci.lifecycle.inithook.InitializationHooksRunner;
import 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.ShutdownEvent;
import io.quarkus.runtime.StartupEvent;
@@ -13,6 +14,8 @@ import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;
import org.jboss.logging.Logger;
+import java.io.IOException;
+
@ApplicationScoped
public class EmulatorLifecycle {
@@ -23,35 +26,48 @@ public class EmulatorLifecycle {
private final EmulatorConfig config;
private final ElastiCacheProxyManager elastiCacheProxyManager;
private final RdsProxyManager rdsProxyManager;
- private final RdsContainerManager rdsContainerManager;
+ private final InitializationHooksRunner initializationHooksRunner;
@Inject
public EmulatorLifecycle(StorageFactory storageFactory, ServiceRegistry serviceRegistry,
EmulatorConfig config, ElastiCacheProxyManager elastiCacheProxyManager,
- RdsProxyManager rdsProxyManager, RdsContainerManager rdsContainerManager) {
+ RdsProxyManager rdsProxyManager, InitializationHooksRunner initializationHooksRunner) {
this.storageFactory = storageFactory;
this.serviceRegistry = serviceRegistry;
this.config = config;
this.elastiCacheProxyManager = elastiCacheProxyManager;
this.rdsProxyManager = rdsProxyManager;
- this.rdsContainerManager = rdsContainerManager;
+ this.initializationHooksRunner = initializationHooksRunner;
}
- void onStart(@Observes StartupEvent event) {
+ void onStart(@Observes StartupEvent ignored) throws IOException, InterruptedException {
LOG.info("=== AWS Local Emulator Starting ===");
LOG.infov("Storage mode: {0}", config.storage().mode());
LOG.infov("Persistent path: {0}", config.storage().persistentPath());
- serviceRegistry.logEnabledServices();
+ serviceRegistry.logEnabledServices();
storageFactory.loadAll();
+ initializationHooksRunner.run(InitializationHook.START);
+
LOG.info("=== AWS Local Emulator Ready ===");
}
- void onStop(@Observes ShutdownEvent event) {
+ void onStop(@Observes ShutdownEvent ignored) throws IOException, InterruptedException {
LOG.info("=== AWS Local Emulator Shutting Down ===");
- elastiCacheProxyManager.stopAll();
- rdsProxyManager.stopAll();
- storageFactory.shutdownAll();
+
+ try {
+ initializationHooksRunner.run(InitializationHook.STOP);
+ } catch (IOException | InterruptedException 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();
+ storageFactory.shutdownAll();
+ }
+
LOG.info("=== AWS Local Emulator Stopped ===");
}
}
diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutor.java b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutor.java
new file mode 100644
index 0000000000..f760f67a90
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutor.java
@@ -0,0 +1,75 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import org.jboss.logging.Logger;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.concurrent.TimeUnit;
+
+@ApplicationScoped
+public class HookScriptExecutor {
+
+ private static final Logger LOG = Logger.getLogger(HookScriptExecutor.class);
+ private final EmulatorConfig.InitHooksConfig initHooksConfig;
+
+ @Inject
+ public HookScriptExecutor(final EmulatorConfig emulatorConfig) {
+ this.initHooksConfig = emulatorConfig.initHooks();
+ }
+
+ public void run(final File hookDirectory, final String scriptFileName) throws IOException, InterruptedException {
+ final String shellExecutable = initHooksConfig.shellExecutable();
+ LOG.debugv("Executing hook script {0} via {1}", scriptFileName, shellExecutable);
+
+ // Inherit parent I/O so script output is streamed directly and does not block on unconsumed buffers.
+ final Process process = new ProcessBuilder(shellExecutable, scriptFileName).directory(hookDirectory).inheritIO().start();
+ run(process, scriptFileName);
+ }
+
+ void run(final Process process, final String scriptFileName) throws InterruptedException {
+ final int exitCode = waitForProcessExitCode(process, scriptFileName);
+ if (exitCode != 0) {
+ final String message = String.format("Hook script failed: %s exited with code %d", scriptFileName, exitCode);
+ throw new IllegalStateException(message);
+ }
+ }
+
+ private int waitForProcessExitCode(final Process process, final String scriptFileName) throws InterruptedException {
+ try {
+ final long timeoutSeconds = initHooksConfig.timeoutSeconds();
+ final boolean finished = process.waitFor(timeoutSeconds, TimeUnit.SECONDS);
+ if (!finished) {
+ LOG.debugv("Hook script exceeded timeout of {0} seconds, terminating process: {1}", timeoutSeconds, scriptFileName);
+ terminateProcess(process, scriptFileName);
+
+ final String message = String.format("Hook script timed out after %d seconds: %s", timeoutSeconds, scriptFileName);
+ throw new IllegalStateException(message);
+ }
+
+ return process.exitValue();
+ } finally {
+ if (process.isAlive()) {
+ LOG.debugv("Hook script process still alive during cleanup, forcing termination: {0}", scriptFileName);
+ process.destroyForcibly();
+ }
+ }
+ }
+
+ private void terminateProcess(final Process process, final String scriptFileName) throws InterruptedException {
+ // Try a graceful shutdown first, then force termination if the process does not exit in time.
+ process.destroy();
+ if (process.isAlive()) {
+ final long shutdownGracePeriodSeconds = initHooksConfig.shutdownGracePeriodSeconds();
+ final boolean terminatedGracefully = process.waitFor(shutdownGracePeriodSeconds, TimeUnit.SECONDS);
+ if (!terminatedGracefully) {
+ LOG.debugv("Hook script process did not terminate gracefully, forcing termination: {0}", scriptFileName);
+ process.destroyForcibly();
+ process.waitFor(shutdownGracePeriodSeconds, TimeUnit.SECONDS);
+ }
+ }
+ }
+
+}
diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHook.java b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHook.java
new file mode 100644
index 0000000000..63e22c7c6c
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHook.java
@@ -0,0 +1,26 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import java.io.File;
+
+public enum InitializationHook {
+
+ STOP("shutdown", "/etc/floci/init/stop.d"),
+ START("startup", "/etc/floci/init/start.d");
+
+ private final String name;
+ private final File path;
+
+ InitializationHook(final String name, final String path) {
+ this.name = name;
+ this.path = new File(path);
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public File getPath() {
+ return path;
+ }
+
+}
diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunner.java b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunner.java
new file mode 100644
index 0000000000..df8d1a2bb3
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunner.java
@@ -0,0 +1,68 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import org.jboss.logging.Logger;
+
+import java.io.File;
+import java.io.FilenameFilter;
+import java.io.IOException;
+import java.util.Arrays;
+
+@ApplicationScoped
+public class InitializationHooksRunner {
+
+ private static final Logger LOG = Logger.getLogger(InitializationHooksRunner.class);
+
+ private static final String SHELL_SCRIPT_EXTENSION = ".sh";
+ private static final FilenameFilter FILE_EXTENSION_FILTER = (ignored, name) -> name.endsWith(SHELL_SCRIPT_EXTENSION);
+
+ private final HookScriptExecutor hookScriptExecutor;
+
+ @Inject
+ public InitializationHooksRunner(final HookScriptExecutor hookScriptExecutor) {
+ this.hookScriptExecutor = hookScriptExecutor;
+ }
+
+ private static String[] findScriptFileNames(final String hookName, final File hookDirectory) {
+ final String hookDirectoryPath = hookDirectory.getAbsolutePath();
+ if (!hookDirectory.exists()) {
+ LOG.debugv("{0} hook directory does not exist: {1}", hookName, hookDirectoryPath);
+ return new String[0];
+ } else if (!hookDirectory.isDirectory()) {
+ LOG.warnv("{0} hook path is not a directory: {1}", hookName, hookDirectoryPath);
+ return new String[0];
+ }
+
+ final String[] scriptFileNames = hookDirectory.list(FILE_EXTENSION_FILTER);
+ if ((scriptFileNames == null) || (scriptFileNames.length == 0)) {
+ LOG.debugv("No {0} hook scripts found in {1}", hookName, hookDirectoryPath);
+ return new String[0];
+ }
+
+ Arrays.sort(scriptFileNames);
+ return scriptFileNames;
+ }
+
+ public void run(final InitializationHook hook) throws IOException, InterruptedException {
+ final String hookName = hook.getName();
+ final File hookDirectory = hook.getPath();
+ run(hookName, hookDirectory);
+ }
+
+ public void run(final String hookName, final File hookDirectory) throws IOException, InterruptedException {
+ final String[] scriptFileNames = findScriptFileNames(hookName, hookDirectory);
+ if (scriptFileNames.length > 0) {
+ final String hookDirectoryPath = hookDirectory.getAbsolutePath();
+ final String scriptList = Arrays.toString(scriptFileNames);
+ LOG.infov("Running {0} hook with {1} script(s) from {2}: {3}", hookName, scriptFileNames.length, hookDirectoryPath, scriptList);
+
+ // Hook scripts are executed sequentially and treated as dependent steps.
+ // Stop at the first script failure to avoid continuing in a partially initialized state
+ for (var scriptFileName : scriptFileNames) {
+ LOG.infov("Executing {0} hook script: {1}", hookName, scriptFileName);
+ hookScriptExecutor.run(hookDirectory, scriptFileName);
+ }
+ }
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutorTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutorTest.java
new file mode 100644
index 0000000000..45ebb7b6aa
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/HookScriptExecutorTest.java
@@ -0,0 +1,181 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Answers;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.Mockito;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.concurrent.TimeUnit;
+
+import static org.mockito.Mockito.times;
+
+@ExtendWith(MockitoExtension.class)
+class HookScriptExecutorTest {
+
+ @Mock(answer = Answers.RETURNS_DEEP_STUBS)
+ private EmulatorConfig emulatorConfigMock;
+
+ @InjectMocks
+ private HookScriptExecutor hookScriptExecutor;
+
+ @Test
+ @DisplayName("Should complete when process exits successfully")
+ void shouldCompleteWhenProcessExitsSuccessfully() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(true);
+ Mockito.when(process.exitValue()).thenReturn(0);
+ Mockito.when(process.isAlive()).thenReturn(false);
+
+ Assertions.assertDoesNotThrow(() -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).waitFor(30L, TimeUnit.SECONDS);
+ Mockito.verify(process).exitValue();
+ Mockito.verify(process, Mockito.never()).destroy();
+ Mockito.verify(process, Mockito.never()).destroyForcibly();
+ }
+
+ @Test
+ @DisplayName("Should throw when process exits with a non-zero code")
+ void shouldThrowWhenProcessExitsWithNonZeroCode() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(true);
+ Mockito.when(process.exitValue()).thenReturn(42);
+ Mockito.when(process.isAlive()).thenReturn(false);
+
+ IllegalStateException exception = Assertions.assertThrows(IllegalStateException.class, () -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).exitValue();
+ Mockito.verify(process, Mockito.never()).destroy();
+
+ Assertions.assertAll(
+ () -> Assertions.assertEquals("Hook script failed: script.sh exited with code 42", exception.getMessage()),
+ () -> Assertions.assertNull(exception.getCause())
+ );
+ }
+
+ @Test
+ @DisplayName("Should terminate process and throw when process times out")
+ void shouldTerminateProcessAndThrowWhenProcessTimesOut() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(emulatorConfigMock.initHooks().shutdownGracePeriodSeconds()).thenReturn(2L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(false);
+ Mockito.when(process.isAlive()).thenReturn(true, false);
+ Mockito.when(process.waitFor(2L, TimeUnit.SECONDS)).thenReturn(false);
+
+ IllegalStateException exception = Assertions.assertThrows(IllegalStateException.class, () -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).destroy();
+ Mockito.verify(process, times(2)).waitFor(2L, TimeUnit.SECONDS);
+ Mockito.verify(process).destroyForcibly();
+
+ Assertions.assertAll(
+ () -> Assertions.assertEquals("Hook script timed out after 30 seconds: script.sh", exception.getMessage()),
+ () -> Assertions.assertNull(exception.getCause())
+ );
+ }
+
+ @Test
+ @DisplayName("Should not force kill when process terminates during grace period")
+ void shouldNotForceKillWhenProcessTerminatesDuringGracePeriod() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(emulatorConfigMock.initHooks().shutdownGracePeriodSeconds()).thenReturn(2L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(false);
+ Mockito.when(process.isAlive()).thenReturn(true, false);
+ Mockito.when(process.waitFor(2L, TimeUnit.SECONDS)).thenReturn(true);
+
+ IllegalStateException exception = Assertions.assertThrows(IllegalStateException.class, () -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).destroy();
+ Mockito.verify(process, Mockito.never()).destroyForcibly();
+
+ Assertions.assertAll(
+ () -> Assertions.assertEquals("Hook script timed out after 30 seconds: script.sh", exception.getMessage()),
+ () -> Assertions.assertNull(exception.getCause())
+ );
+ }
+
+ @Test
+ @DisplayName("Should force cleanup when interrupted while waiting")
+ void shouldForceCleanupWhenInterruptedWhileWaiting() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ InterruptedException exception = new InterruptedException("boom");
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenThrow(exception);
+ Mockito.when(process.isAlive()).thenReturn(true);
+
+ InterruptedException thrown = Assertions.assertThrows(InterruptedException.class, () -> hookScriptExecutor.run(process, "script.sh"));
+
+ Assertions.assertSame(exception, thrown);
+ Mockito.verify(process).destroyForcibly();
+ }
+
+ @Test
+ @DisplayName("Should force cleanup when process is still alive in finally")
+ void shouldForceCleanupWhenProcessIsStillAliveInFinally() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(true);
+ Mockito.when(process.exitValue()).thenReturn(0);
+ Mockito.when(process.isAlive()).thenReturn(true);
+
+ Assertions.assertDoesNotThrow(() -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).destroyForcibly();
+ }
+
+ @Test
+ @DisplayName("Should not wait for grace period when process stops immediately after destroy")
+ void shouldNotWaitForGracePeriodWhenProcessStopsImmediatelyAfterDestroy() throws InterruptedException {
+ Process process = Mockito.mock(Process.class);
+
+ Mockito.when(emulatorConfigMock.initHooks().timeoutSeconds()).thenReturn(30L);
+ Mockito.when(process.waitFor(30L, TimeUnit.SECONDS)).thenReturn(false);
+ Mockito.when(process.isAlive()).thenReturn(false, false);
+
+ IllegalStateException exception = Assertions.assertThrows(IllegalStateException.class, () -> hookScriptExecutor.run(process, "script.sh"));
+
+ Mockito.verify(process).destroy();
+ Mockito.verify(process, Mockito.never()).waitFor(2L, TimeUnit.SECONDS);
+ Mockito.verify(process, Mockito.never()).destroyForcibly();
+
+ Assertions.assertAll(
+ () -> Assertions.assertEquals("Hook script timed out after 30 seconds: script.sh", exception.getMessage()),
+ () -> Assertions.assertNull(exception.getCause())
+ );
+ }
+
+ @Test
+ @DisplayName("Should throw IOException when shell executable does not exist")
+ void shouldThrowIOExceptionWhenShellExecutableDoesNotExist() {
+ File hookDirectory = new File(".");
+
+ Mockito.when(emulatorConfigMock.initHooks().shellExecutable()).thenReturn("/definitely/missing/bash");
+
+ IOException exception = Assertions.assertThrows(IOException.class, () -> hookScriptExecutor.run(hookDirectory, "script.sh"));
+
+ Assertions.assertAll(
+ () -> Assertions.assertNotNull(exception.getMessage()),
+ () -> Assertions.assertTrue(exception.getMessage().startsWith("Cannot run program")),
+ () -> Assertions.assertTrue(exception.getMessage().contains("\"/definitely/missing/bash\""))
+ );
+ }
+
+}
diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerIntegrationTest.java
new file mode 100644
index 0000000000..44deb24405
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerIntegrationTest.java
@@ -0,0 +1,221 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import io.quarkus.test.junit.QuarkusTest;
+import jakarta.inject.Inject;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+@QuarkusTest
+class InitializationHooksRunnerIntegrationTest {
+
+ @Inject
+ private InitializationHooksRunner initializationHooksRunner;
+
+ @TempDir
+ private Path hookScriptsDirectory;
+
+ @Test
+ @DisplayName("Should execute startup hook scripts in lexicographical order")
+ void shouldExecuteRealScriptsInLexicographicalOrder() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Path absoluteOutputFile = outputFile.toAbsolutePath();
+ String bootstrapScript = """
+ #!/bin/bash
+ echo bootstrap >> "%s"
+ """.formatted(absoluteOutputFile);
+ String seedResourcesScript = """
+ #!/bin/bash
+ echo seed-resources >> "%s"
+ """.formatted(absoluteOutputFile);
+
+ Files.writeString(hookScriptsDirectory.resolve("20-seed-resources.sh"), seedResourcesScript);
+ Files.writeString(hookScriptsDirectory.resolve("10-bootstrap.sh"), bootstrapScript);
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ List<String> expectedLines = List.of("bootstrap", "seed-resources");
+ List<String> lines = Files.readAllLines(outputFile);
+ Assertions.assertEquals(expectedLines, lines);
+ }
+
+ @Test
+ @DisplayName("Should ignore non-shell files in the hook directory")
+ void shouldIgnoreNonShellScriptFiles() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Path absoluteOutputFile = outputFile.toAbsolutePath();
+ String bootstrapScript = """
+ #!/bin/bash
+ echo bootstrap >> "%s"
+ """.formatted(absoluteOutputFile);
+ String seedResourcesScript = """
+ #!/bin/bash
+ echo seed-resources >> "%s"
+ """.formatted(absoluteOutputFile);
+
+ Files.writeString(hookScriptsDirectory.resolve("10-bootstrap.sh"), bootstrapScript);
+ Files.writeString(hookScriptsDirectory.resolve("15-notes.txt"), "ignored");
+ Files.writeString(hookScriptsDirectory.resolve("20-seed-resources.sh"), seedResourcesScript);
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ List<String> expectedLines = List.of("bootstrap", "seed-resources");
+ List<String> lines = Files.readAllLines(outputFile);
+ Assertions.assertEquals(expectedLines, lines);
+ }
+
+ @Test
+ @DisplayName("Should use lexicographical ordering for numbered hook file names")
+ void shouldExecuteScriptsUsingLexicographicalFileNameOrder() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Path absoluteOutputFile = outputFile.toAbsolutePath();
+ String configureDomainScript = """
+ #!/bin/bash
+ echo configure-domain >> "%s"
+ """.formatted(absoluteOutputFile);
+ String bootstrapScript = """
+ #!/bin/bash
+ echo bootstrap >> "%s"
+ """.formatted(absoluteOutputFile);
+ String createBucketsScript = """
+ #!/bin/bash
+ echo create-buckets >> "%s"
+ """.formatted(absoluteOutputFile);
+
+ Files.writeString(hookScriptsDirectory.resolve("10-configure-domain.sh"), configureDomainScript);
+ Files.writeString(hookScriptsDirectory.resolve("01-bootstrap.sh"), bootstrapScript);
+ Files.writeString(hookScriptsDirectory.resolve("02-create-buckets.sh"), createBucketsScript);
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ List<String> expectedLines = List.of("bootstrap", "create-buckets", "configure-domain");
+ List<String> lines = Files.readAllLines(outputFile);
+ Assertions.assertEquals(expectedLines, lines);
+ }
+
+ @Test
+ @DisplayName("Should do nothing when the hook directory contains no shell scripts")
+ void shouldDoNothingWhenDirectoryContainsNoShellScripts() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Files.writeString(hookScriptsDirectory.resolve("README.txt"), "hook documentation");
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Assertions.assertFalse(Files.exists(outputFile));
+ }
+
+ @Test
+ @DisplayName("Should do nothing when the hook directory does not exist")
+ void shouldDoNothingWhenHookDirectoryDoesNotExist() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ Path missingHookDirectory = hookScriptsDirectory.resolve("missing");
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+
+ initializationHooksRunner.run("startup", missingHookDirectory.toFile());
+
+ Assertions.assertFalse(Files.exists(outputFile));
+ }
+
+ @Test
+ @DisplayName("Should do nothing when the hook path is not a directory")
+ void shouldDoNothingWhenHookPathIsNotADirectory() throws IOException, InterruptedException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ Path hookPathFile = hookScriptsDirectory.resolve("hook-file.txt");
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Files.writeString(hookPathFile, "ignored");
+
+ initializationHooksRunner.run("startup", hookPathFile.toFile());
+
+ Assertions.assertFalse(Files.exists(outputFile));
+ }
+
+ @Test
+ @DisplayName("Should stop executing startup hooks after the first failing script")
+ void shouldStopAtFirstFailingScript() throws IOException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Path absoluteOutputFile = outputFile.toAbsolutePath();
+ String bootstrapScript = """
+ #!/bin/bash
+ echo bootstrap >> "%s"
+ """.formatted(absoluteOutputFile);
+ String failingScript = """
+ #!/bin/bash
+ exit 42
+ """;
+ String seedDataScript = """
+ #!/bin/bash
+ echo seed-data >> "%s"
+ """.formatted(absoluteOutputFile);
+
+ Files.writeString(hookScriptsDirectory.resolve("10-bootstrap.sh"), bootstrapScript);
+ Files.writeString(hookScriptsDirectory.resolve("20-create-queue.sh"), failingScript);
+ Files.writeString(hookScriptsDirectory.resolve("30-seed-data.sh"), seedDataScript);
+
+ Assertions.assertThrows(IllegalStateException.class, () -> initializationHooksRunner.run("startup", hookDirectory));
+ Assertions.assertEquals(List.of("bootstrap"), Files.readAllLines(outputFile));
+ }
+
+ @Test
+ @DisplayName("Should stop executing startup hooks after the first timed out script")
+ void shouldStopAtFirstTimedOutScript() throws IOException {
+ Path bashExecutable = Path.of("/bin/bash");
+ Assumptions.assumeTrue(Files.isExecutable(bashExecutable));
+
+ File hookDirectory = hookScriptsDirectory.toFile();
+ Path outputFile = hookScriptsDirectory.resolve("output.txt");
+ Path absoluteOutputFile = outputFile.toAbsolutePath();
+ String bootstrapScript = """
+ #!/bin/bash
+ echo bootstrap >> "%s"
+ """.formatted(absoluteOutputFile);
+ String timeoutScript = """
+ #!/bin/bash
+ sleep 6
+ """;
+ String publishEventsScript = """
+ #!/bin/bash
+ echo publish-events >> "%s"
+ """.formatted(absoluteOutputFile);
+
+ Files.writeString(hookScriptsDirectory.resolve("10-bootstrap.sh"), bootstrapScript);
+ Files.writeString(hookScriptsDirectory.resolve("20-seed-fixtures.sh"), timeoutScript);
+ Files.writeString(hookScriptsDirectory.resolve("30-publish-events.sh"), publishEventsScript);
+
+ Assertions.assertThrows(IllegalStateException.class, () -> initializationHooksRunner.run("startup", hookDirectory));
+
+ List<String> expectedLines = List.of("bootstrap");
+ List<String> lines = Files.readAllLines(outputFile);
+ Assertions.assertEquals(expectedLines, lines);
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerTest.java
new file mode 100644
index 0000000000..7d1f5c0283
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/inithook/InitializationHooksRunnerTest.java
@@ -0,0 +1,155 @@
+package io.github.hectorvent.floci.lifecycle.inithook;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentMatchers;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.Mockito;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.io.File;
+import java.io.IOException;
+
+@ExtendWith(MockitoExtension.class)
+class InitializationHooksRunnerTest {
+
+ @Mock
+ private HookScriptExecutor hookScriptExecutorMock;
+
+ @InjectMocks
+ private InitializationHooksRunner initializationHooksRunner;
+
+ @Test
+ @DisplayName("Should execute shell scripts in sorted order")
+ void shouldExecuteShellScriptsInSortedOrder() throws IOException, InterruptedException {
+ File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(new String[]{"20-third.sh", "10-first.sh", "15-second.sh"});
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ var inOrder = Mockito.inOrder(hookScriptExecutorMock);
+ inOrder.verify(hookScriptExecutorMock).run(hookDirectory, "10-first.sh");
+ inOrder.verify(hookScriptExecutorMock).run(hookDirectory, "15-second.sh");
+ inOrder.verify(hookScriptExecutorMock).run(hookDirectory, "20-third.sh");
+ inOrder.verifyNoMoreInteractions();
+ }
+
+ @Test
+ @DisplayName("Should ignore directories without shell scripts")
+ void shouldIgnoreDirectoriesWithoutShellScripts() throws IOException, InterruptedException {
+ File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(new String[0]);
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ Mockito.verifyNoInteractions(hookScriptExecutorMock);
+ }
+
+ @Test
+ @DisplayName("Should ignore hook directory when listing scripts returns null")
+ void shouldIgnoreHookDirectoryWhenListingScriptsReturnsNull() throws IOException, InterruptedException {
+ final File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(null);
+
+ initializationHooksRunner.run("startup", hookDirectory);
+
+ Mockito.verifyNoInteractions(hookScriptExecutorMock);
+ }
+
+ @Test
+ @DisplayName("Should ignore missing hook directory")
+ void shouldIgnoreMissingHookDirectory() throws IOException, InterruptedException {
+ File missingHookDirectory = Mockito.mock(File.class);
+ Mockito.when(missingHookDirectory.getAbsolutePath()).thenReturn("/hooks/missing");
+ Mockito.when(missingHookDirectory.exists()).thenReturn(false);
+
+ initializationHooksRunner.run("startup", missingHookDirectory);
+
+ Mockito.verifyNoInteractions(hookScriptExecutorMock);
+ }
+
+ @Test
+ @DisplayName("Should ignore hook path that is not a directory")
+ void shouldIgnoreHookPathThatIsNotADirectory() throws IOException, InterruptedException {
+ File hookPath = Mockito.mock(File.class);
+ Mockito.when(hookPath.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookPath.exists()).thenReturn(true);
+ Mockito.when(hookPath.isDirectory()).thenReturn(false);
+
+ initializationHooksRunner.run("startup", hookPath);
+
+ Mockito.verifyNoInteractions(hookScriptExecutorMock);
+ }
+
+ @Test
+ @DisplayName("Should stop at first script failure")
+ void shouldStopAtFirstScriptFailure() throws IOException, InterruptedException {
+ File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(new String[]{"10-first.sh", "20-failing.sh", "30-never-runs.sh"});
+
+ Mockito.doNothing().when(hookScriptExecutorMock).run(hookDirectory, "10-first.sh");
+
+ IllegalStateException illegalStateException = new IllegalStateException("Hook script failed: 20-failing.sh exited with code 127");
+ Mockito.doThrow(illegalStateException).when(hookScriptExecutorMock).run(hookDirectory, "20-failing.sh");
+
+ IllegalStateException exception = Assertions.assertThrows(IllegalStateException.class, () -> initializationHooksRunner.run("startup", hookDirectory));
+ Assertions.assertSame(illegalStateException, exception);
+
+ var inOrder = Mockito.inOrder(hookScriptExecutorMock);
+ inOrder.verify(hookScriptExecutorMock).run(hookDirectory, "10-first.sh");
+ inOrder.verify(hookScriptExecutorMock).run(hookDirectory, "20-failing.sh");
+ inOrder.verifyNoMoreInteractions();
+ }
+
+ @Test
+ @DisplayName("Should propagate IOException from hook script executor")
+ void shouldPropagateIOExceptionFromHookScriptExecutor() throws IOException, InterruptedException {
+ File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(new String[]{"10-bootstrap.sh"});
+
+ IOException ioException = new IOException("Cannot execute hook script");
+ Mockito.doThrow(ioException).when(hookScriptExecutorMock).run(hookDirectory, "10-bootstrap.sh");
+
+ IOException exception = Assertions.assertThrows(IOException.class, () -> initializationHooksRunner.run("startup", hookDirectory));
+
+ Mockito.verify(hookScriptExecutorMock).run(hookDirectory, "10-bootstrap.sh");
+ Assertions.assertSame(ioException, exception);
+ }
+
+ @Test
+ @DisplayName("Should propagate InterruptedException from hook script executor")
+ void shouldPropagateInterruptedExceptionFromHookScriptExecutor() throws IOException, InterruptedException {
+ File hookDirectory = Mockito.mock(File.class);
+ Mockito.when(hookDirectory.getAbsolutePath()).thenReturn("/hooks/startup");
+ Mockito.when(hookDirectory.exists()).thenReturn(true);
+ Mockito.when(hookDirectory.isDirectory()).thenReturn(true);
+ Mockito.when(hookDirectory.list(ArgumentMatchers.any())).thenReturn(new String[]{"10-bootstrap.sh"});
+
+ InterruptedException interruptedException = new InterruptedException("Hook execution interrupted");
+ Mockito.doThrow(interruptedException).when(hookScriptExecutorMock).run(hookDirectory, "10-bootstrap.sh");
+
+ InterruptedException exception = Assertions.assertThrows(InterruptedException.class, () -> initializationHooksRunner.run("startup", hookDirectory));
+
+ Mockito.verify(hookScriptExecutorMock).run(hookDirectory, "10-bootstrap.sh");
+ Assertions.assertSame(interruptedException, exception);
+ }
+
+}
diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml
index 591746108a..d3c0c033d1 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -45,6 +45,11 @@ floci:
validate-signatures: false
presign-secret: test-secret
+ init-hooks:
+ shell-executable: /bin/bash
+ timeout-seconds: 5
+ shutdown-grace-period-seconds: 2
+
services:
ssm:
enabled: true
@@ -97,4 +102,4 @@ floci:
stepfunctions:
enabled: true
cloudformation:
- enabled: true
\ No newline at end of file
+ enabled: true