Light, fluffy, and always free - The AWS Local Emulator alternative
feat(ui): serve the Console Contract v2 manifest and pass its URL to the console (#6711)
Hector Ventura258994c1b99d
diff --git a/docs/ui/console-contract.md b/docs/ui/console-contract.mdindex 2c012aa5a9..2d45d4b706 100644--- a/docs/ui/console-contract.md+++ b/docs/ui/console-contract.md@@ -9,6 +9,11 @@ operator sets one image name and Floci does the rest.If you are running a console rather than writing one, see [Web Console](index.md).+**Console Contract v2** extends this page for every Floci emulator (AWS, Azure, GCP, OCI) without changing+anything below: it adds `FLOCI_INFO_URL` and the emulator manifest at `GET /_floci/info`, described in+[The manifest](#the-manifest). The full v2 text is published with+[floci-az](https://floci.io/floci-az/ui/console-contract/).+## The short versionThree things make a console a Floci console:@@ -39,7 +44,8 @@ credential discovery.| `AWS_SECRET_ACCESS_KEY` | `test` | Placeholder. || `AWS_SESSION_TOKEN` | `test` | Placeholder. || `PORT` | `4500` | The port the console MUST listen on. |-| `FLOCI_CLOUD` | `aws` | Which emulator this is: `aws`, `gcp`, `az` or `oci`. |+| `FLOCI_CLOUD` | `aws` | Which emulator this is: `aws`, `gcp`, `az` or `oci`. A console SHOULD open on this cloud and offer only it. |+| `FLOCI_INFO_URL` | `http://floci:4566/_floci/info` | The [manifest](#the-manifest), at the address the console reaches Floci on (v2). || `FLOCI_TLS_SKIP_VERIFY` | `1` | Present only when the operator opted out of TLS verification. || `NODE_TLS_REJECT_UNAUTHORIZED` | `0` | The same instruction in the form a Node or Bun client honours. |@@ -122,6 +128,34 @@ The health endpoint MUST NOT require authentication, and SHOULD respond within a- The console MAY be stateless and MUST tolerate being stopped and recreated at any time: Flocirecreates it whenever the endpoint it was built with no longer addresses the running Floci.+## The manifest++`GET /_floci/info` describes the running emulator (v2). A console MAY read it at `FLOCI_INFO_URL`, and MUST+ignore keys it does not know:++```json+{+ "manifest_version": 1,+ "console_contract": 2,+ "cloud": "aws",+ "emulator": "floci",+ "version": "2.3.0",+ "edition": "community",+ "original_edition": "floci-always-free",+ "dynamodb_backend": "local",+ "endpoint": "http://localhost:4566",+ "health_url": "/_floci/health",+ "tls": {"enabled": false},+ "services": {"ec2": "enabled", "s3": "enabled"},+ "defaults": {"region": "us-east-1", "account_id": "000000000000"},+ "ui": {"enabled": true, "port": 4500}+}+```++`services` lists every service as `enabled` or `disabled` (`running` and `available` in `/_floci/health`).+`version`, `edition`, `original_edition` and `dynamodb_backend` are the keys `/_floci/info` returned before+the manifest; they stay.+## Self-description labelsA console whose shape differs from the contract's defaults can say so in its own image labels,diff --git a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoController.java b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoController.javaindex cc071ca274..a3d271d6aa 100644--- a/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoController.java+++ b/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoController.java@@ -29,12 +29,15 @@ import java.util.LinkedHashMap;import java.util.List;import java.util.Map;import java.util.Optional;+import java.util.TreeMap;@Path("{prefix:(_floci|_localstack)}")@Produces(MediaType.APPLICATION_JSON)public class EmulatorInfoController {private static final Logger LOG = Logger.getLogger(EmulatorInfoController.class);+ static final int MANIFEST_VERSION = 1;+ static final int CONSOLE_CONTRACT = 2;private final ServiceRegistry serviceRegistry;private final InitLifecycleState initLifecycleState;@@ -99,11 +102,48 @@ public class EmulatorInfoController {return Response.ok(body).build();}+ /**+ * The emulator manifest of the Floci Console Contract v2: what a web console, or a script, needs to+ * know about this emulator. Additive over the original {@code version}, {@code edition},+ * {@code original_edition} and {@code dynamodb_backend} keys, which stay as they were.+ */@GET@Path("/info")public Response info() {- return Response.ok(Map.of("version", version, "edition", "community", "original_edition", "floci-always-free",- "dynamodb_backend", dynamoDbBackendSelector.selected())).build();+ Map<String, Object> body = new LinkedHashMap<>();+ body.put("manifest_version", MANIFEST_VERSION);+ body.put("console_contract", CONSOLE_CONTRACT);+ body.put("cloud", "aws");+ body.put("emulator", "floci");+ body.put("version", version);+ body.put("edition", "community");+ body.put("original_edition", "floci-always-free");+ body.put("dynamodb_backend", dynamoDbBackendSelector.selected());+ body.put("endpoint", config.effectiveBaseUrl());+ body.put("health_url", "/_floci/health");+ body.put("tls", Map.of("enabled", config.tls().enabled()));+ body.put("services", manifestServices(serviceRegistry.getServices()));++ Map<String, Object> defaults = new LinkedHashMap<>();+ defaults.put("region", config.defaultRegion());+ defaults.put("account_id", config.defaultAccountId());+ body.put("defaults", defaults);++ Map<String, Object> ui = new LinkedHashMap<>();+ ui.put("enabled", config.services().ui().enabled());+ ui.put("port", config.services().ui().port());+ body.put("ui", ui);+ return Response.ok(body).build();+ }++ /**+ * The health map's {@code running} and {@code available}, as the manifest's {@code enabled} and+ * {@code disabled}.+ */+ static Map<String, String> manifestServices(Map<String, String> healthServices) {+ Map<String, String> services = new TreeMap<>();+ healthServices.forEach((name, status) -> services.put(name, "running".equals(status) ? "enabled" : "disabled"));+ return services;}@GETdiff --git a/src/main/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManager.java b/src/main/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManager.javaindex 2b90810237..5978456c2c 100644--- a/src/main/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManager.java+++ b/src/main/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManager.java@@ -355,6 +355,7 @@ public class FlociUiManager {}env.put(PORT_ENV, String.valueOf(console.internalPort()));env.put("FLOCI_CLOUD", FLOCI_CLOUD);+ env.put("FLOCI_INFO_URL", infoUrl(endpoint));if (config.services().ui().insecureSkipTlsVerify()) {LOG.warn("floci.services.ui.insecure-skip-tls-verify=true: the web console sidecar will "+ "not verify Floci's TLS certificate. Intended for Floci's self-signed "@@ -370,6 +371,12 @@ public class FlociUiManager {return rendered;}+ /** Console Contract v2's {@code FLOCI_INFO_URL}: the manifest, at the address the console reaches Floci on. */+ static String infoUrl(String endpoint) {+ String base = endpoint.endsWith("/") ? endpoint.substring(0, endpoint.length() - 1) : endpoint;+ return base + "/_floci/info";+ }+/*** Merges operator-supplied {@code KEY=VALUE} entries over the injected defaults.*diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerIntegrationTest.javaindex 45d82fd359..e8f58ecd04 100644--- a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerIntegrationTest.java+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerIntegrationTest.java@@ -68,6 +68,26 @@ class EmulatorInfoControllerIntegrationTest {}}+ @ParameterizedTest+ @ValueSource(strings = {"/_floci/info", "/_localstack/info"})+ void info_isTheConsoleContractManifestOnBothPaths(String path) {+ given()+ .when().get(path)+ .then()+ .statusCode(200)+ .contentType("application/json")+ .body("manifest_version", equalTo(1))+ .body("console_contract", equalTo(2))+ .body("cloud", equalTo("aws"))+ .body("health_url", equalTo("/_floci/health"))+ .body("services.s3", equalTo("enabled"))+ .body("defaults.region", equalTo("us-east-1"))+ .body("defaults.account_id", equalTo("000000000000"))+ .body("ui.port", equalTo(4500))+ .body("version", equalTo(FlociVersion.current()))+ .body("dynamodb_backend", notNullValue());+ }+@ParameterizedTest@ValueSource(strings = {"/_floci/init", "/_localstack/init"})void init_returnsLifecycleStateOnBothPaths(String path) {diff --git a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerTest.java b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerTest.javaindex 547b0423c9..fda42a53d3 100644--- a/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerTest.java+++ b/src/test/java/io/github/hectorvent/floci/lifecycle/EmulatorInfoControllerTest.java@@ -23,6 +23,7 @@ import java.util.Map;import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertSame;import static org.junit.jupiter.api.Assertions.assertThrows;+import static org.mockito.Mockito.RETURNS_DEEP_STUBS;import static org.mockito.Mockito.doThrow;import static org.mockito.Mockito.inOrder;import static org.mockito.Mockito.lenient;@@ -61,11 +62,45 @@ class EmulatorInfoControllerTest {void info_reportsTheSelectedDynamoDbBackend() {when(dynamoDbBackendSelector.selected()).thenReturn("local");- Map<?, ?> info = (Map<?, ?>) controller.info().getEntity();+ Map<?, ?> info = (Map<?, ?>) manifestController().info().getEntity();assertEquals("local", info.get("dynamodb_backend"));}+ @Test+ void info_isTheConsoleContractManifest() {+ EmulatorConfig manifestConfig = mock(EmulatorConfig.class, RETURNS_DEEP_STUBS);+ when(manifestConfig.effectiveBaseUrl()).thenReturn("http://floci:4566");+ when(manifestConfig.defaultRegion()).thenReturn("us-east-1");+ when(manifestConfig.defaultAccountId()).thenReturn("000000000000");+ when(manifestConfig.tls().enabled()).thenReturn(true);+ when(manifestConfig.services().ui().enabled()).thenReturn(true);+ when(manifestConfig.services().ui().port()).thenReturn(4500);+ when(serviceRegistry.getServices()).thenReturn(Map.of("s3", "running", "ec2", "available"));++ Map<?, ?> info = (Map<?, ?>) new EmulatorInfoController(serviceRegistry, initLifecycleState, storageFactory,+ resettables, containerTeardowns, certificateAuthority, manifestConfig, dynamoDbBackendSelector)+ .info().getEntity();++ assertEquals(1, info.get("manifest_version"));+ assertEquals(2, info.get("console_contract"));+ assertEquals("aws", info.get("cloud"));+ assertEquals("floci", info.get("emulator"));+ assertEquals("http://floci:4566", info.get("endpoint"));+ assertEquals("/_floci/health", info.get("health_url"));+ assertEquals(Map.of("enabled", true), info.get("tls"));+ assertEquals(Map.of("ec2", "disabled", "s3", "enabled"), info.get("services"));+ assertEquals(Map.of("region", "us-east-1", "account_id", "000000000000"), info.get("defaults"));+ assertEquals(Map.of("enabled", true, "port", 4500), info.get("ui"));+ assertEquals("community", info.get("edition"), "the original keys stay");+ }++ private EmulatorInfoController manifestController() {+ return new EmulatorInfoController(serviceRegistry, initLifecycleState, storageFactory,+ resettables, containerTeardowns, certificateAuthority, mock(EmulatorConfig.class, RETURNS_DEEP_STUBS),+ dynamoDbBackendSelector);+ }+@Test@DisplayName("Should stop every managed container before wiping storage on reset")void reset_stopsManagedContainersBeforeClearingStorage() {diff --git a/src/test/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManagerTest.java b/src/test/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManagerTest.javaindex cab06bfee9..00dddf5186 100644--- a/src/test/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManagerTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/floci/ui/FlociUiManagerTest.java@@ -689,9 +689,16 @@ class FlociUiManagerTest {assertTrue(env.contains("AWS_REGION=us-east-1"), env.toString());assertTrue(env.contains("AWS_DEFAULT_REGION=us-east-1"), env.toString());assertTrue(env.contains("FLOCI_CLOUD=aws"), env.toString());+ assertTrue(env.contains("FLOCI_INFO_URL=http://floci:4566/_floci/info"), env.toString());assertTrue(env.contains("PORT=4500"), env.toString());}+ @Test+ void theManifestUrlNeverDoublesTheSlash() {+ assertEquals("http://floci:4566/_floci/info", FlociUiManager.infoUrl("http://floci:4566/"));+ assertEquals("http://floci:4566/_floci/info", FlociUiManager.infoUrl("http://floci:4566"));+ }+@Testvoid theConsoleIsNeverHandedFlocisOwnAwsCredentials() {// The baseline forwards Floci's ambient credentials when none are supplied, which is