Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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 version
Three 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: Floci
recreates 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 labels
A 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.java
index 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;
}
@GET
diff --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.java
index 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.java
index 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.java
index 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.java
index 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"));
+ }
+
@Test
void theConsoleIsNeverHandedFlocisOwnAwsCredentials() {
// The baseline forwards Floci's ambient credentials when none are supplied, which is