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.mdindex 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 valuereturn `TooManyRequestsException` (HTTP 429). Functions without a reserveddiff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.java b/src/main/java/io/github/hectorvent/floci/services/lambda/LambdaService.javaindex 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.javaindex 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.javaindex 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 specContainerBuilder.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.javaindex 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.javaindex 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javanew file mode 100644index 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();+ }+}