Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(lambda): implement reactive S3-to-Lambda sync for hot-reloading (#509)

Hector Ventura114fade12926
diff --git a/docs/services/lambda.md b/docs/services/lambda.md
index 7e516f8824..e5e8377ac5 100644
--- a/docs/services/lambda.md
+++ b/docs/services/lambda.md
@@ -43,6 +43,41 @@ Lambda runs your function code inside real Docker containers — the same way re
| `GetFunctionConcurrency` | Get reserved concurrent executions |
| `DeleteFunctionConcurrency` | Clear reserved concurrent executions |
+## Hot-Reloading via Reactive S3 Sync
+
+Floci supports an automatic hot-reloading mechanism when functions are deployed via S3. This follows the standard AWS behavior where S3 and Lambda interact, but is optimized for a seamless local development experience.
+
+When a Lambda function is created using an S3 bucket and key, Floci maintains a link between the function and its source object. Any subsequent update to that S3 object (e.g., via `s3:PutObject`) automatically triggers a reactive synchronization:
+
+1. **Detection**: Floci detects the S3 update via an internal event system.
+2. **Synchronization**: The new code is automatically re-extracted to the local code storage.
+3. **Invalidation**: Any active "warm" containers for that function are proactively drained.
+4. **Reload**: The very next invocation starts a fresh container with the updated code.
+
+This allows you to update your Lambda code by simply re-uploading your ZIP to S3, without having to manually call `UpdateFunctionCode` or restart any containers.
+
+### Example
+
+```bash
+# 1. Create a function linked to S3
+aws lambda create-function \
+ --function-name my-function \
+ --code S3Bucket=my-bucket,S3Key=function.zip \
+ ...
+
+# 2. Invoke (starts a warm container)
+aws lambda invoke --function-name my-function out.json
+
+# 3. Update the code in S3 (Triggers Reactive Sync)
+aws s3 cp updated-function.zip s3://my-bucket/function.zip
+
+# 4. Invoke again (automatically picks up the new code)
+aws lambda invoke --function-name my-function out.json
+```
+
+!!! note "Standard Behavior"
+ This mechanism requires no custom configuration or non-standard magic strings. It works with standard AWS SDKs and CLI tools, providing a "live" development feel while staying within the AWS API contract.
+
!!! note "Concurrency enforcement"
Reserved concurrency is enforced: invocations beyond the reserved value
return `TooManyRequestsException` (HTTP 429). Functions without a reserved
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.java b/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.java
index 24bb9b1e00..0d50cae754 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.java
@@ -15,9 +15,11 @@ import io.github.hectorvent.floci.services.lambda.zip.CodeStore;
import io.github.hectorvent.floci.services.lambda.zip.ZipExtractor;
import io.github.hectorvent.floci.services.s3.S3Service;
import io.github.hectorvent.floci.services.s3.model.S3Object;
+import io.github.hectorvent.floci.services.s3.model.S3ObjectUpdatedEvent;
import io.github.hectorvent.floci.services.sqs.SqsService;
import jakarta.annotation.PostConstruct;
import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;
import org.jboss.logging.Logger;
@@ -240,6 +242,8 @@ public class LambdaService {
}
String zipFileBase64 = (String) code.get("ZipFile");
if (zipFileBase64 != null) {
+ fn.setS3Bucket(null);
+ fn.setS3Key(null);
extractZipCode(fn, zipFileBase64);
}
String s3Bucket = (String) code.get("S3Bucket");
@@ -304,6 +308,8 @@ public class LambdaService {
String s3Key = (String) request.get("S3Key");
if (zipFileBase64 != null) {
+ fn.setS3Bucket(null);
+ fn.setS3Key(null);
extractZipCode(fn, zipFileBase64);
}
if (imageUri != null) {
@@ -951,6 +957,9 @@ public class LambdaService {
if (s3Service == null) {
throw new AwsException("ServiceUnavailableException", "S3 service not available", 503);
}
+
+ fn.setS3Bucket(s3Bucket);
+ fn.setS3Key(s3Key);
S3Object obj;
try {
obj = s3Service.getObject(s3Bucket, s3Key);
@@ -1087,4 +1096,34 @@ public class LambdaService {
return defaultValue;
}
}
+
+ /**
+ * Observes S3 object updates and triggers reactive sync for any Lambda
+ * functions linked to the updated object.
+ */
+ public void onS3ObjectUpdated(@Observes S3ObjectUpdatedEvent event) {
+ LOG.debugv("Observing S3 update: {0}/{1}", event.bucketName(), event.key());
+ // For simplicity, we scan all functions in the default region
+ // Most local dev setups use a single region
+ String region = regionResolver.getDefaultRegion();
+ List<LambdaFunction> functions = functionStore.list(region);
+ for (LambdaFunction fn : functions) {
+ if (event.bucketName().equals(fn.getS3Bucket()) && event.key().equals(fn.getS3Key())) {
+ LOG.infov("Reactive S3 Sync: updating function {0} from s3://{1}/{2}",
+ fn.getFunctionName(), event.bucketName(), event.key());
+ try {
+ S3Object obj = s3Service.getObject(event.bucketName(), event.key());
+ extractZipCode(fn, Base64.getEncoder().encodeToString(obj.getData()));
+ fn.setLastModified(Instant.now().toEpochMilli());
+ fn.setRevisionId(UUID.randomUUID().toString());
+ functionStore.save(region, fn);
+
+ // Push to warm workers
+ warmPool.pushCodeUpdate(fn);
+ } catch (Exception e) {
+ LOG.warnv("Failed reactive sync for function {0}: {1}", fn.getFunctionName(), e.getMessage());
+ }
+ }
+ }
+ }
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/WarmPool.java b/src/main/java/io/github/hectorvent/floci/services/lambda/WarmPool.java
index b5a180c068..6e204ecdb6 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/WarmPool.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/WarmPool.java
@@ -150,6 +150,16 @@ public class WarmPool {
}
}
+ /**
+ * Pushes a code update to all warm containers in the pool for the given function.
+ * In this implementation, we drain the containers to force a fresh start with new code.
+ */
+ public void pushCodeUpdate(LambdaFunction fn) {
+ LOG.infov("Reactive S3 Sync: invalidating warm pool for function {0} to pick up new code",
+ fn.getFunctionName());
+ drainFunction(fn.getFunctionName());
+ }
+
/**
* Stops and removes all warm containers for the given function.
* Called on function delete or code update.
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
index ff887a33d6..f59f23fe38 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
@@ -150,7 +150,6 @@ public class ContainerLauncher {
String shortId = java.util.UUID.randomUUID().toString().replace("-", "").substring(0, 8);
String containerName = "floci-" + fn.getFunctionName() + "-" + shortId;
- // Build container spec
ContainerBuilder.Builder specBuilder = containerBuilder.newContainer(image)
.withName(containerName)
.withEnv(env)
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/model/LambdaFunction.java b/src/main/java/io/github/hectorvent/floci/services/lambda/model/LambdaFunction.java
index 29a55da155..6733120466 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/model/LambdaFunction.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/model/LambdaFunction.java
@@ -28,6 +28,8 @@ public class LambdaFunction {
private String packageType = "Zip";
private String imageUri;
private String codeLocalPath;
+ private String s3Bucket;
+ private String s3Key;
private Map<String, String> environment = new HashMap<>();
private Map<String, String> tags = new HashMap<>();
private List<Map<String, Object>> policies = new ArrayList<>();
@@ -88,6 +90,12 @@ public class LambdaFunction {
public String getCodeLocalPath() { return codeLocalPath; }
public void setCodeLocalPath(String codeLocalPath) { this.codeLocalPath = codeLocalPath; }
+ public String getS3Bucket() { return s3Bucket; }
+ public void setS3Bucket(String s3Bucket) { this.s3Bucket = s3Bucket; }
+
+ public String getS3Key() { return s3Key; }
+ public void setS3Key(String s3Key) { this.s3Key = s3Key; }
+
public Map<String, String> getEnvironment() { return environment; }
public void setEnvironment(Map<String, String> environment) { this.environment = environment; }
diff --git a/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java b/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java
index 5536350c9b..346f6802bf 100644
--- a/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java
+++ b/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java
@@ -18,6 +18,7 @@ import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Event;
import jakarta.enterprise.inject.Instance;
import jakarta.inject.Inject;
import org.jboss.logging.Logger;
@@ -63,6 +64,7 @@ public class S3Service {
private final Instance<LambdaService> lambdaServiceProvider;
private final LambdaInvoker lambdaInvoker;
private final EventBridgeService eventBridgeService;
+ private final Event<S3ObjectUpdatedEvent> s3UpdatedEvent;
private final RegionResolver regionResolver;
private final String baseUrl;
private final ObjectMapper objectMapper;
@@ -72,6 +74,7 @@ public class S3Service {
SqsService sqsService, SnsService snsService,
Instance<LambdaService> lambdaServiceProvider,
EventBridgeService eventBridgeService,
+ Event<S3ObjectUpdatedEvent> s3UpdatedEvent,
RegionResolver regionResolver,
ObjectMapper objectMapper) {
this(
@@ -84,7 +87,7 @@ public class S3Service {
Path.of(config.storage().persistentPath()).resolve("s3"),
"memory".equals(config.storage().services().s3().mode().orElse(config.storage().mode())),
sqsService, snsService, null, lambdaServiceProvider, null,
- eventBridgeService,
+ eventBridgeService, s3UpdatedEvent,
regionResolver,
config.effectiveBaseUrl(), objectMapper
);
@@ -97,7 +100,7 @@ public class S3Service {
StorageBackend<String, S3Object> objectStore,
Path dataRoot, boolean inMemory) {
this(bucketStore, objectStore, dataRoot, inMemory, null, null, null, null, null, null, null,
- "http://localhost:4566", new ObjectMapper());
+ null, "http://localhost:4566", new ObjectMapper());
}
S3Service(StorageBackend<String, Bucket> bucketStore,
@@ -105,8 +108,8 @@ public class S3Service {
Path dataRoot, boolean inMemory,
LambdaService lambdaService,
RegionResolver regionResolver) {
- this(bucketStore, objectStore, dataRoot, inMemory, null, null, lambdaService, null, null, null, regionResolver,
- "http://localhost:4566", new ObjectMapper());
+ this(bucketStore, objectStore, dataRoot, inMemory, null, null, lambdaService, null, null, null, null,
+ regionResolver, "http://localhost:4566", new ObjectMapper());
}
S3Service(StorageBackend<String, Bucket> bucketStore,
@@ -114,8 +117,8 @@ public class S3Service {
Path dataRoot, boolean inMemory,
LambdaInvoker lambdaInvoker,
RegionResolver regionResolver) {
- this(bucketStore, objectStore, dataRoot, inMemory, null, null, null, null, lambdaInvoker, null, regionResolver,
- "http://localhost:4566", new ObjectMapper());
+ this(bucketStore, objectStore, dataRoot, inMemory, null, null, null, null, lambdaInvoker, null, null,
+ regionResolver, "http://localhost:4566", new ObjectMapper());
}
private S3Service(StorageBackend<String, Bucket> bucketStore,
@@ -125,6 +128,7 @@ public class S3Service {
Instance<LambdaService> lambdaServiceProvider,
LambdaInvoker lambdaInvoker,
EventBridgeService eventBridgeService,
+ Event<S3ObjectUpdatedEvent> s3UpdatedEvent,
RegionResolver regionResolver, String baseUrl, ObjectMapper objectMapper) {
this.bucketStore = bucketStore;
this.objectStore = objectStore;
@@ -136,6 +140,7 @@ public class S3Service {
this.lambdaServiceProvider = lambdaServiceProvider;
this.lambdaInvoker = lambdaInvoker;
this.eventBridgeService = eventBridgeService;
+ this.s3UpdatedEvent = s3UpdatedEvent;
this.regionResolver = regionResolver;
this.baseUrl = baseUrl;
this.objectMapper = objectMapper;
@@ -1462,6 +1467,9 @@ public class S3Service {
}
private void fireNotifications(String bucketName, String key, String eventName, S3Object obj) {
+ if (s3UpdatedEvent != null && eventName.startsWith("ObjectCreated")) {
+ s3UpdatedEvent.fire(new S3ObjectUpdatedEvent(bucketName, key));
+ }
if (sqsService == null && snsService == null && lambdaService == null
&& lambdaServiceProvider == null && lambdaInvoker == null && eventBridgeService == null) {
return;
diff --git a/src/main/java/io/github/hectorvent/floci/services/s3/model/S3ObjectUpdatedEvent.java b/src/main/java/io/github/hectorvent/floci/services/s3/model/S3ObjectUpdatedEvent.java
new file mode 100644
index 0000000000..29f1d625d9
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/s3/model/S3ObjectUpdatedEvent.java
@@ -0,0 +1,11 @@
+package io.github.hectorvent.floci.services.s3.model;
+
+/**
+ * Internal event fired when an S3 object is created or updated.
+ * Observed by other services (like Lambda) to trigger reactive behaviors.
+ *
+ * @param bucketName the name of the bucket
+ * @param key the object key
+ */
+public record S3ObjectUpdatedEvent(String bucketName, String key) {
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/LambdaReactiveSyncIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/LambdaReactiveSyncIntegrationTest.java
new file mode 100644
index 0000000000..5c55a379fc
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/LambdaReactiveSyncIntegrationTest.java
@@ -0,0 +1,101 @@
+package io.github.hectorvent.floci.services.lambda;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+
+import java.io.ByteArrayOutputStream;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipOutputStream;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.equalTo;
+
+/**
+ * Verifies that updating a ZIP file in S3 automatically patches
+ * running Lambda containers linked to that bucket/key.
+ */
+@QuarkusTest
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class LambdaReactiveSyncIntegrationTest {
+
+ private static final String BUCKET = "reactive-sync-bucket";
+ private static final String KEY = "function.zip";
+ private static final String FN = "reactive-sync-fn";
+
+ private static byte[] makeZip(String body) throws Exception {
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ try (ZipOutputStream zos = new ZipOutputStream(baos)) {
+ zos.putNextEntry(new ZipEntry("index.js"));
+ zos.write(("exports.handler = async (e) => ({ body: '" + body + "' });").getBytes());
+ zos.closeEntry();
+ }
+ return baos.toByteArray();
+ }
+
+ @Test
+ @Order(1)
+ void setupAndInitialInvoke() throws Exception {
+ // 1. Create bucket and upload V1
+ given().when().put("/" + BUCKET).then().statusCode(200);
+ given().body(makeZip("v1")).when().put("/" + BUCKET + "/" + KEY).then().statusCode(200);
+
+ // 2. Create function
+ given()
+ .contentType("application/json")
+ .body("""
+ {
+ "FunctionName": "%s",
+ "Runtime": "nodejs20.x",
+ "Role": "arn:aws:iam::000000000000:role/role",
+ "Handler": "index.handler",
+ "Timeout": 30,
+ "Code": {
+ "S3Bucket": "%s",
+ "S3Key": "%s"
+ }
+ }
+ """.formatted(FN, BUCKET, KEY))
+ .when()
+ .post("/2015-03-31/functions")
+ .then()
+ .statusCode(201);
+
+ // 3. First invoke (starts container)
+ given()
+ .body("{}")
+ .when()
+ .post("/2015-03-31/functions/" + FN + "/invocations")
+ .then()
+ .statusCode(200)
+ .body(containsString("v1"));
+ }
+
+ @Test
+ @Order(2)
+ void uploadV2AndVerifyAutoSync() throws Exception {
+ // 1. Upload V2 to same bucket/key
+ given().body(makeZip("v2")).when().put("/" + BUCKET + "/" + KEY).then().statusCode(200);
+
+ // 2. Wait a bit for async event processing and Docker copy
+ Thread.sleep(5000);
+
+ // 3. Invoke again. Should see V2 without calling UpdateFunctionCode
+ given()
+ .body("{}")
+ .when()
+ .post("/2015-03-31/functions/" + FN + "/invocations")
+ .then()
+ .statusCode(200)
+ .body(containsString("v2"));
+ }
+
+ @Test
+ @Order(3)
+ void cleanup() {
+ given().when().delete("/2015-03-31/functions/" + FN).then().statusCode(204);
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java
new file mode 100644
index 0000000000..cbb25289e3
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java
@@ -0,0 +1,100 @@
+package io.github.hectorvent.floci.services.lambda.launcher;
+
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.github.hectorvent.floci.core.common.docker.ContainerBuilder;
+import io.github.hectorvent.floci.core.common.docker.ContainerLifecycleManager;
+import io.github.hectorvent.floci.core.common.docker.ContainerLogStreamer;
+import io.github.hectorvent.floci.core.common.docker.ContainerSpec;
+import io.github.hectorvent.floci.core.common.docker.DockerHostResolver;
+import io.github.hectorvent.floci.services.ecr.registry.EcrRegistryManager;
+import io.github.hectorvent.floci.services.lambda.model.LambdaFunction;
+import io.github.hectorvent.floci.services.lambda.runtime.RuntimeApiServer;
+import io.github.hectorvent.floci.services.lambda.runtime.RuntimeApiServerFactory;
+import com.github.dockerjava.api.DockerClient;
+import com.github.dockerjava.api.model.Bind;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import org.junit.jupiter.api.io.TempDir;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class ContainerLauncherTest {
+
+ @Mock ContainerLifecycleManager lifecycleManager;
+ @Mock ContainerLogStreamer logStreamer;
+ @Mock ImageResolver imageResolver;
+ @Mock RuntimeApiServerFactory runtimeApiServerFactory;
+ @Mock DockerHostResolver dockerHostResolver;
+ @Mock EmulatorConfig config;
+ @Mock EcrRegistryManager ecrRegistryManager;
+ @Mock RuntimeApiServer runtimeApiServer;
+ @Mock DockerClient dockerClient;
+
+ @TempDir
+ Path tempDir;
+
+ ContainerLauncher launcher;
+ ContainerBuilder containerBuilder;
+
+ @BeforeEach
+ void setUp() {
+ // Setup config mocks
+ EmulatorConfig.ServicesConfig services = mock(EmulatorConfig.ServicesConfig.class);
+ EmulatorConfig.LambdaServiceConfig lambda = mock(EmulatorConfig.LambdaServiceConfig.class);
+ EmulatorConfig.DockerConfig docker = mock(EmulatorConfig.DockerConfig.class);
+
+ when(config.services()).thenReturn(services);
+ when(services.lambda()).thenReturn(lambda);
+ when(lambda.dockerNetwork()).thenReturn(Optional.empty());
+ when(config.docker()).thenReturn(docker);
+ when(docker.logMaxSize()).thenReturn("10m");
+ when(docker.logMaxFile()).thenReturn("3");
+
+ containerBuilder = new ContainerBuilder(config, dockerHostResolver);
+ launcher = new ContainerLauncher(containerBuilder, lifecycleManager, logStreamer, imageResolver,
+ runtimeApiServerFactory, dockerHostResolver, config, ecrRegistryManager);
+
+ when(runtimeApiServerFactory.create()).thenReturn(runtimeApiServer);
+ when(runtimeApiServer.getPort()).thenReturn(9000);
+ when(dockerHostResolver.resolve()).thenReturn("127.0.0.1");
+
+ ContainerLifecycleManager.ContainerInfo info = new ContainerLifecycleManager.ContainerInfo("c1", Map.of());
+ when(lifecycleManager.createAndStart(any())).thenReturn(info);
+ when(lifecycleManager.getDockerClient()).thenReturn(dockerClient);
+ }
+
+ @Test
+ void launchFunctionCopiesCode() throws Exception {
+ Path codePath = Files.createDirectory(tempDir.resolve("code"));
+
+ LambdaFunction fn = new LambdaFunction();
+ fn.setFunctionName("standard-fn");
+ fn.setRuntime("nodejs20.x");
+ fn.setHandler("index.handler");
+ fn.setCodeLocalPath(codePath.toString());
+
+ launcher.launch(fn);
+
+ ArgumentCaptor<ContainerSpec> specCaptor = ArgumentCaptor.forClass(ContainerSpec.class);
+ verify(lifecycleManager).createAndStart(specCaptor.capture());
+
+ ContainerSpec spec = specCaptor.getValue();
+ assertTrue(spec.binds().isEmpty(), "Function should NOT have bind mounts");
+
+ // Function should attempt to copy code
+ verify(lifecycleManager, atLeastOnce()).getDockerClient();
+ }
+}