Light, fluffy, and always free - The AWS Local Emulator alternative
feat(neptune): support neo4j backend for openCypher via NEPTUNE_DB_TYPE (#1449)
Stuart Lang760d48b91aab
diff --git a/README.md b/README.mdindex 318c80330a..14e957ce7c 100644--- a/README.md+++ b/README.md@@ -264,7 +264,7 @@ For operation-level compatibility, see the [Services Overview](https://floci.io/| ElastiCache | Real Docker | Redis / Valkey protocol, IAM auth, SigV4 validation || RDS | Real Docker | PostgreSQL, MySQL, MariaDB, IAM auth, JDBC-compatible engines || RDS Data API | REST JSON over real RDS containers | Raw SQL execution and transactions for local MySQL / MariaDB RDS resources |-| Neptune | Real Docker | Graph DB via TinkerPop Gremlin Server; RDS-shaped control plane; Gremlin WebSocket on port 8182 with SigV4 proxy |+| Neptune | Real Docker | Graph DB via TinkerPop Gremlin Server (default) or Neo4j for openCypher/Bolt (`NEPTUNE_DB_TYPE`); RDS-shaped control plane; SigV4 proxy on port 8182 || DocumentDB | Real Docker, mock mode available | MongoDB-compatible cluster via real MongoDB containers; RDS-shaped control plane; MongoDB wire protocol on port 27017 || MSK | Real Docker | Kafka-compatible broker via Redpanda || Athena | In-process with DuckDB sidecar | Real SQL execution over S3 and Glue-backed views |@@ -315,6 +315,7 @@ Floci uses real Docker containers when in-process emulation would reduce fidelit| RDS MySQL / Aurora | `mysql:8.0` | MySQL engine, IAM auth, JDBC-compatible access || RDS MariaDB | `mariadb:11` | MariaDB engine, IAM auth, JDBC-compatible access || Neptune | `tinkerpop/gremlin-server:3.7.3` | TinkerPop Gremlin Server; Gremlin WebSocket on port 8182; SigV4 auth proxy |+| Neptune (openCypher) | `neo4j:5-community` | Neo4j backend when `FLOCI_SERVICES_NEPTUNE_DB_TYPE=neo4j`; openCypher over Bolt || DocumentDB | `mongo:7.0` | MongoDB engine; MongoDB wire protocol on port 27017 || MSK | `redpandadata/redpanda:latest` | Kafka-compatible broker via Redpanda || EC2 | AMI-mapped Linux images | Linux containers, SSH key injection, UserData, IMDS, IAM credentials |@@ -345,6 +346,7 @@ docker run -d --name floci \| `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` || `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` || `FLOCI_SERVICES_NEPTUNE_DEFAULT_IMAGE` | `tinkerpop/gremlin-server:3.7.3` |+| `FLOCI_SERVICES_NEPTUNE_DEFAULT_NEO4J_IMAGE` | `neo4j:5-community` || `FLOCI_SERVICES_DOCDB_DEFAULT_IMAGE` | `mongo:7.0` || `FLOCI_SERVICES_EKS_DEFAULT_IMAGE` | `rancher/k3s:latest` || `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` |diff --git a/docs/services/neptune.md b/docs/services/neptune.mdindex f61cc863e5..342487d05c 100644--- a/docs/services/neptune.md+++ b/docs/services/neptune.md@@ -1,10 +1,21 @@# Neptune-**Protocol:** Query (XML) for management API + Gremlin / HTTP for data plane+**Protocol:** Query (XML) for management API + Gremlin / HTTP / Bolt for data plane**Management Endpoint:** `POST http://localhost:4566/`-**Data Endpoint:** `localhost:<proxy-port>` (TCP / WebSocket)+**Data Endpoint:** `localhost:<proxy-port>` (TCP / WebSocket / Bolt)-Floci manages real [Apache TinkerPop Gremlin Server](https://tinkerpop.apache.org/) Docker containers and proxies connections to them, providing an API-compatible Neptune emulation for local development and testing.+Floci manages real graph-database Docker containers and proxies connections to them, providing an API-compatible Neptune emulation for local development and testing.++## Backend engine (`db-type`)++Neptune supports multiple query languages. Floci backs each one with a different container and proxies the matching wire protocol, selected globally via `FLOCI_SERVICES_NEPTUNE_DB_TYPE` (mirroring LocalStack's `NEPTUNE_DB_TYPE`):++| `db-type` | Backend image | Query language | Wire protocol |+|-----------|---------------|----------------|---------------|+| `gremlin` _(default)_ | [Apache TinkerPop Gremlin Server](https://tinkerpop.apache.org/) | Gremlin | WebSocket |+| `neo4j` | [Neo4j](https://neo4j.com/) | openCypher | Bolt |++The proxy is a transparent byte relay, so the host-facing proxy port range is unchanged regardless of engine — only the protocol you connect with differs. Connect to a cluster's proxy port (from the `8182`–`8282` range, returned by `DescribeDBClusters`), not the backend's native port. The Neo4j backend runs with `NEO4J_AUTH=none`, matching Neptune's model of authenticating at the AWS edge (IAM) rather than at the graph protocol; connect your Bolt/openCypher driver with no auth.## Supported Actions@@ -25,8 +36,10 @@ Floci manages real [Apache TinkerPop Gremlin Server](https://tinkerpop.apache.or|----------|---------|-------------|| `FLOCI_SERVICES_NEPTUNE_ENABLED` | `true` | Enable or disable Neptune || `FLOCI_SERVICES_NEPTUNE_PROXY_BASE_PORT` | `8182` | First host port in the Gremlin proxy range |-| `FLOCI_SERVICES_NEPTUNE_PROXY_MAX_PORT` | `8282` | Last host port in the Gremlin proxy range |-| `FLOCI_SERVICES_NEPTUNE_DEFAULT_IMAGE` | `tinkerpop/gremlin-server:3.7.3` | Gremlin Server Docker image |+| `FLOCI_SERVICES_NEPTUNE_PROXY_MAX_PORT` | `8282` | Last host port in the proxy range |+| `FLOCI_SERVICES_NEPTUNE_DB_TYPE` | `gremlin` | Backend engine: `gremlin` (Gremlin/WebSocket) or `neo4j` (openCypher/Bolt) |+| `FLOCI_SERVICES_NEPTUNE_DEFAULT_IMAGE` | `tinkerpop/gremlin-server:3.7.3` | Image used when `db-type=gremlin` |+| `FLOCI_SERVICES_NEPTUNE_DEFAULT_NEO4J_IMAGE` | `neo4j:5-community` | Image used when `db-type=neo4j` || `FLOCI_SERVICES_NEPTUNE_DOCKER_NETWORK` | _(host default)_ | Docker network for container connectivity |### Docker Compose@@ -105,6 +118,25 @@ print(result)gremlin.close()```+### Graph data plane — openCypher (Python + neo4j driver)++Start Floci with `FLOCI_SERVICES_NEPTUNE_DB_TYPE=neo4j`, then connect with any Bolt+driver and run openCypher:++```python+from neo4j import GraphDatabase++# Use the port returned by DescribeDBClusters; no auth (NEO4J_AUTH=none)+driver = GraphDatabase.driver("bolt://localhost:8182", auth=None)++with driver.session() as session:+ session.run("CREATE (:Person {name: 'Alice'})")+ count = session.run("MATCH (p:Person) RETURN count(p) AS c").single()["c"]+ print(count)++driver.close()+```+### Management API (Python / boto3)```pythondiff --git a/pom.xml b/pom.xmlindex 40da3a84a7..39efbb9b2b 100644--- a/pom.xml+++ b/pom.xml@@ -239,6 +239,13 @@<version>2.3.232</version><scope>test</scope></dependency>+ <!-- openCypher/Bolt client for the Neptune neo4j db-type integration test -->+ <dependency>+ <groupId>org.neo4j.driver</groupId>+ <artifactId>neo4j-java-driver</artifactId>+ <version>5.28.5</version>+ <scope>test</scope>+ </dependency></dependencies><build>diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.javaindex 468952a024..f356b9fae5 100644--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java@@ -585,9 +585,22 @@ public interface EmulatorConfig {@WithDefault("8282")int proxyMaxPort();+ /**+ * Backend graph engine and query language: {@code gremlin} (Apache TinkerPop, Gremlin+ * over WebSocket) or {@code neo4j} (Neo4j, openCypher over Bolt). Mirrors LocalStack's+ * {@code NEPTUNE_DB_TYPE}.+ */+ @WithDefault("gremlin")+ String dbType();++ /** Image used when {@code db-type=gremlin}. */@WithDefault("tinkerpop/gremlin-server:3.7.3")String defaultImage();+ /** Image used when {@code db-type=neo4j} (openCypher / Bolt). */+ @WithDefault("neo4j:5-community")+ String defaultNeo4jImage();+Optional<String> dockerNetwork();}diff --git a/src/main/java/io/github/hectorvent/floci/services/neptune/NeptuneService.java b/src/main/java/io/github/hectorvent/floci/services/neptune/NeptuneService.javaindex 6b980ce8f7..fd64687bd6 100644--- a/src/main/java/io/github/hectorvent/floci/services/neptune/NeptuneService.java+++ b/src/main/java/io/github/hectorvent/floci/services/neptune/NeptuneService.java@@ -9,6 +9,7 @@ import io.github.hectorvent.floci.core.storage.StorageFactory;import io.github.hectorvent.floci.services.neptune.container.NeptuneContainerHandle;import io.github.hectorvent.floci.services.neptune.container.NeptuneContainerManager;import io.github.hectorvent.floci.services.neptune.model.NeptuneCluster;+import io.github.hectorvent.floci.services.neptune.model.NeptuneDbType;import io.github.hectorvent.floci.services.neptune.model.NeptuneInstance;import io.github.hectorvent.floci.services.neptune.proxy.NeptuneProxyManager;import jakarta.enterprise.context.ApplicationScoped;@@ -62,11 +63,21 @@ public class NeptuneService {}int proxyPort = allocateProxyPort();- String image = config.services().neptune().defaultImage();-- LOG.infov("Creating Neptune cluster {0} on proxy port {1}, image={2}", id, String.valueOf(proxyPort), image);-- NeptuneContainerHandle handle = containerManager.start(id, image);+ String configuredDbType = config.services().neptune().dbType();+ NeptuneDbType dbType = NeptuneDbType.fromConfig(configuredDbType).orElseGet(() -> {+ LOG.warnv("Unsupported Neptune db-type ''{0}'', falling back to {1}. Supported: gremlin, neo4j.",+ configuredDbType, NeptuneDbType.GREMLIN);+ return NeptuneDbType.GREMLIN;+ });+ String image = switch (dbType) {+ case GREMLIN -> config.services().neptune().defaultImage();+ case NEO4J -> config.services().neptune().defaultNeo4jImage();+ };++ LOG.infov("Creating Neptune cluster {0} on proxy port {1}, dbType={2}, image={3}",+ id, String.valueOf(proxyPort), dbType, image);++ NeptuneContainerHandle handle = containerManager.start(id, image, dbType);String region = regionResolver.getDefaultRegion();String endpointHost = resolveEndpointHost();@@ -92,7 +103,8 @@ public class NeptuneService {proxyManager.startProxy(id, proxyPort, handle.getHost(), handle.getPort());clusters.put(id, cluster);- LOG.infov("Neptune cluster {0} created, Gremlin endpoint={1}:{2}", id, endpointHost, String.valueOf(proxyPort));+ LOG.infov("Neptune cluster {0} created ({1}), endpoint={2}:{3}",+ id, dbType, endpointHost, String.valueOf(proxyPort));return cluster;}diff --git a/src/main/java/io/github/hectorvent/floci/services/neptune/container/NeptuneContainerManager.java b/src/main/java/io/github/hectorvent/floci/services/neptune/container/NeptuneContainerManager.javaindex 7bf8a21df5..1d794f158a 100644--- a/src/main/java/io/github/hectorvent/floci/services/neptune/container/NeptuneContainerManager.java+++ b/src/main/java/io/github/hectorvent/floci/services/neptune/container/NeptuneContainerManager.java@@ -9,6 +9,7 @@ import io.github.hectorvent.floci.core.common.docker.ContainerLifecycleManager.Cimport io.github.hectorvent.floci.core.common.docker.ContainerLifecycleManager.EndpointInfo;import io.github.hectorvent.floci.core.common.docker.ContainerLogStreamer;import io.github.hectorvent.floci.core.common.docker.ContainerSpec;+import io.github.hectorvent.floci.services.neptune.model.NeptuneDbType;import jakarta.enterprise.context.ApplicationScoped;import jakarta.inject.Inject;import org.jboss.logging.Logger;@@ -26,13 +27,13 @@ import java.util.concurrent.ConcurrentHashMap;/*** Manages backend Docker container lifecycle for Neptune DB clusters.- * Spins up a TinkerPop Gremlin Server container per cluster.+ * Spins up one graph database container per cluster — a TinkerPop Gremlin Server+ * ({@code db-type=gremlin}) or Neo4j ({@code db-type=neo4j}, openCypher over Bolt).*/@ApplicationScopedpublic class NeptuneContainerManager {private static final Logger LOG = Logger.getLogger(NeptuneContainerManager.class);- private static final int GREMLIN_PORT = 8182;private static final int BACKEND_READY_DEADLINE_MS = 60_000;private static final int BACKEND_READY_RETRY_MS = 200;private static final int BACKEND_PROBE_CONNECT_MS = 2_000;@@ -60,28 +61,30 @@ public class NeptuneContainerManager {this.regionResolver = regionResolver;}- public NeptuneContainerHandle start(String clusterId, String image) {- LOG.infov("Starting Neptune Gremlin Server container for cluster: {0}", clusterId);+ public NeptuneContainerHandle start(String clusterId, String image, NeptuneDbType dbType) {+ LOG.infov("Starting Neptune backend container ({0}) for cluster: {1}", dbType, clusterId);+ int backendPort = dbType.backendPort();String containerName = "floci-neptune-" + clusterId;lifecycleManager.removeIfExists(containerName);ContainerBuilder.Builder specBuilder = containerBuilder.newContainer(image).withName(containerName)+ .withEnv(backendEnv(dbType)).withDockerNetwork(config.services().neptune().dockerNetwork()).withLogRotation();if (!containerDetector.isRunningInContainer()) {- specBuilder.withDynamicPort(GREMLIN_PORT);+ specBuilder.withDynamicPort(backendPort);} else {- specBuilder.withExposedPort(GREMLIN_PORT);+ specBuilder.withExposedPort(backendPort);}ContainerSpec spec = specBuilder.build();ContainerInfo info = lifecycleManager.createAndStart(spec);- EndpointInfo endpoint = info.getEndpoint(GREMLIN_PORT);+ EndpointInfo endpoint = info.getEndpoint(backendPort);- LOG.infov("Neptune Gremlin Server for cluster {0}: {1}", clusterId, endpoint);+ LOG.infov("Neptune {0} backend for cluster {1}: {2}", dbType, clusterId, endpoint);NeptuneContainerHandle handle = new NeptuneContainerHandle(info.containerId(), clusterId, endpoint.host(), endpoint.port());@@ -90,7 +93,7 @@ public class NeptuneContainerManager {String shortId = info.containerId().length() >= 8? info.containerId().substring(0, 8): info.containerId();- String logGroup = "/aws/neptune/cluster/" + clusterId + "/gremlin-log";+ String logGroup = "/aws/neptune/cluster/" + clusterId + "/" + dbType.name().toLowerCase() + "-log";String logStream = logStreamer.generateLogStreamName(shortId);String region = regionResolver.getDefaultRegion();@@ -98,11 +101,24 @@ public class NeptuneContainerManager {info.containerId(), logGroup, logStream, region, "neptune:" + clusterId);handle.setLogStream(logHandle);- waitForBackendReady(clusterId, endpoint.host(), endpoint.port());+ waitForBackendReady(clusterId, dbType, endpoint.host(), endpoint.port());return handle;}+ /**+ * Environment for the backend container. Neo4j's Bolt endpoint requires auth to be+ * explicitly disabled so the transparent proxy can relay openCypher sessions without+ * brokering credentials — matching Neptune, which authenticates at the AWS edge (IAM),+ * not at the graph protocol.+ */+ private static List<String> backendEnv(NeptuneDbType dbType) {+ return switch (dbType) {+ case GREMLIN -> List.of();+ case NEO4J -> List.of("NEO4J_AUTH=none");+ };+ }+public void stop(NeptuneContainerHandle handle) {if (handle == null) {return;@@ -122,12 +138,32 @@ public class NeptuneContainerManager {}/**- * Probes the Gremlin Server HTTP endpoint. Gremlin Server responds to a plain HTTP GET- * on /gremlin with HTTP 400 (not a WebSocket upgrade), confirming the server is listening.+ * Bolt handshake magic preamble {@code 0x6060B017} followed by four 4-byte version+ * proposals (highest first). Neo4j replies with the 4-byte agreed version once its Bolt+ * connector is accepting connections, which is the readiness signal we probe for.+ */+ private static final byte[] BOLT_HANDSHAKE = {+ 0x60, 0x60, (byte) 0xB0, 0x17, // magic preamble+ 0x00, 0x00, 0x00, 0x05, // propose Bolt 5.0+ 0x00, 0x00, 0x00, 0x04, // propose Bolt 4.0+ 0x00, 0x00, 0x00, 0x00,+ 0x00, 0x00, 0x00, 0x00+ };++ /**+ * Waits until the backend's native data-plane protocol is answering. The probe payload and+ * expected response differ per engine:+ * <ul>+ * <li>Gremlin Server replies to a plain HTTP {@code GET /gremlin} (HTTP 400, not a+ * WebSocket upgrade), confirming it is listening.</li>+ * <li>Neo4j replies to the Bolt handshake with a 4-byte agreed version.</li>+ * </ul>*/- private static void waitForBackendReady(String clusterId, String host, int port) {- byte[] probe = "GET /gremlin HTTP/1.1\r\nHost: floci\r\n\r\n"- .getBytes(StandardCharsets.UTF_8);+ private static void waitForBackendReady(String clusterId, NeptuneDbType dbType, String host, int port) {+ byte[] probe = switch (dbType) {+ case GREMLIN -> "GET /gremlin HTTP/1.1\r\nHost: floci\r\n\r\n".getBytes(StandardCharsets.UTF_8);+ case NEO4J -> BOLT_HANDSHAKE;+ };long deadline = System.currentTimeMillis() + BACKEND_READY_DEADLINE_MS;int attempt = 0;while (System.currentTimeMillis() < deadline) {@@ -140,17 +176,17 @@ public class NeptuneContainerManager {out.flush();byte[] buf = new byte[32];int n = s.getInputStream().read(buf);- if (n > 0) {+ if (probeIndicatesReady(dbType, buf, n)) {if (attempt > 1) {- LOG.infov("Gremlin backend ready for cluster {0} after {1} probe attempt(s)",- clusterId, attempt);+ LOG.infov("Neptune {0} backend ready for cluster {1} after {2} probe attempt(s)",+ dbType, clusterId, attempt);}return;}} catch (IOException e) {if (LOG.isDebugEnabled()) {- LOG.debugv("Gremlin probe for cluster {0} attempt {1}: {2}",- clusterId, attempt, e.getMessage());+ LOG.debugv("Neptune {0} probe for cluster {1} attempt {2}: {3}",+ dbType, clusterId, attempt, e.getMessage());}}try {@@ -158,11 +194,28 @@ public class NeptuneContainerManager {} catch (InterruptedException ie) {Thread.currentThread().interrupt();throw new RuntimeException(- "Interrupted while waiting for Gremlin backend " + clusterId, ie);+ "Interrupted while waiting for Neptune " + dbType + " backend " + clusterId, ie);}}throw new RuntimeException(- "Gremlin backend for cluster " + clusterId + " did not become ready on "+ "Neptune " + dbType + " backend for cluster " + clusterId + " did not become ready on "+ host + ":" + port + " within " + BACKEND_READY_DEADLINE_MS + "ms");}++ /**+ * Decides whether a probe response signals readiness. For Gremlin any reply confirms the+ * server is listening. For Neo4j the Bolt handshake reply is the 4-byte agreed version;+ * an all-zero version ({@code 0x00000000}) means the connector answered but rejected every+ * proposed Bolt version, so the backend is reachable but unusable — treat it as not-ready+ * and keep retrying rather than handing back a cluster whose sessions will fail.+ */+ private static boolean probeIndicatesReady(NeptuneDbType dbType, byte[] response, int n) {+ if (n <= 0) {+ return false;+ }+ return switch (dbType) {+ case GREMLIN -> true;+ case NEO4J -> n >= 4 && (response[0] | response[1] | response[2] | response[3]) != 0;+ };+ }}diff --git a/src/main/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbType.java b/src/main/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbType.javanew file mode 100644index 0000000000..56bab887cd--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbType.java@@ -0,0 +1,52 @@+package io.github.hectorvent.floci.services.neptune.model;++import java.util.Optional;++/**+ * Backend graph database engine used to emulate a Neptune cluster.+ *+ * <p>Amazon Neptune exposes several query languages over its data-plane endpoint. Floci backs+ * each one with a different container image and proxies the matching wire protocol:+ * <ul>+ * <li>{@link #GREMLIN} — Apache TinkerPop Gremlin Server. Gremlin traversals over a+ * WebSocket on port 8182 (Neptune's native default).</li>+ * <li>{@link #NEO4J} — Neo4j. openCypher queries over the Bolt protocol on port 7687,+ * matching Neptune's openCypher / Bolt endpoint.</li>+ * </ul>+ *+ * <p>The engine is selected globally via {@code FLOCI_SERVICES_NEPTUNE_DB_TYPE}, mirroring+ * LocalStack's {@code NEPTUNE_DB_TYPE} toggle.+ */+public enum NeptuneDbType {++ GREMLIN(8182),+ NEO4J(7687);++ private final int backendPort;++ NeptuneDbType(int backendPort) {+ this.backendPort = backendPort;+ }++ /** Container port the backend listens on for its native data-plane protocol. */+ public int backendPort() {+ return backendPort;+ }++ /**+ * Resolves a configured db-type string (case-insensitive) to an engine.+ * Empty / null falls back to {@link #GREMLIN} to preserve historical behaviour.+ * An unrecognised value returns {@link Optional#empty()} so the caller can fall back+ * to the default rather than failing the client's request over a server-side typo.+ */+ public static Optional<NeptuneDbType> fromConfig(String value) {+ if (value == null || value.isBlank()) {+ return Optional.of(GREMLIN);+ }+ return switch (value.trim().toLowerCase()) {+ case "gremlin", "tinkerpop" -> Optional.of(GREMLIN);+ case "neo4j", "opencypher", "cypher", "bolt" -> Optional.of(NEO4J);+ default -> Optional.empty();+ };+ }+}diff --git a/src/main/resources/application.yml b/src/main/resources/application.ymlindex 14c60f2773..89c578c6c2 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -207,7 +207,9 @@ floci:enabled: trueproxy-base-port: 8182proxy-max-port: 8282+ db-type: "gremlin"default-image: "tinkerpop/gremlin-server:3.7.3"+ default-neo4j-image: "neo4j:5-community"eventbridge:enabled: truecloudmap:diff --git a/src/test/java/io/github/hectorvent/floci/services/neptune/NeptuneOpenCypherIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/neptune/NeptuneOpenCypherIntegrationTest.javanew file mode 100644index 0000000000..ce16de8c98--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/neptune/NeptuneOpenCypherIntegrationTest.java@@ -0,0 +1,95 @@+package io.github.hectorvent.floci.services.neptune;++import io.quarkus.test.junit.QuarkusTest;+import io.quarkus.test.junit.QuarkusTestProfile;+import io.quarkus.test.junit.TestProfile;+import org.junit.jupiter.api.Test;+import org.neo4j.driver.AuthTokens;+import org.neo4j.driver.Driver;+import org.neo4j.driver.GraphDatabase;+import org.neo4j.driver.Session;++import java.util.Map;+import java.util.regex.Matcher;+import java.util.regex.Pattern;++import static io.restassured.RestAssured.given;+import static org.junit.jupiter.api.Assertions.assertEquals;++/**+ * Demonstrates that a Neptune cluster configured with {@code db-type=neo4j} speaks the+ * openCypher query language over the Bolt protocol.+ *+ * <p>The default Gremlin backend ({@code tinkerpop/gremlin-server}) does NOT understand+ * openCypher/Bolt, so before {@code db-type} support existed this test could not pass —+ * the proxied port served a Gremlin WebSocket endpoint, not a Bolt endpoint.+ */+@QuarkusTest+@TestProfile(NeptuneOpenCypherIntegrationTest.Neo4jDbTypeProfile.class)+class NeptuneOpenCypherIntegrationTest {++ private static final String FORM = "application/x-www-form-urlencoded";+ private static final String CLUSTER_ID = "opencypher-cluster";++ // Fake SigV4 header whose credential scope service is "neptune" routes the management+ // request (CreateDBCluster/DeleteDBCluster) to the Neptune service.+ private static final String AUTH =+ "AWS4-HMAC-SHA256 Credential=test/20260516/us-east-1/neptune/aws4_request, " ++ "SignedHeaders=content-type;host, Signature=test";++ private static final Pattern PORT = Pattern.compile("<Port>(\\d+)</Port>");++ @Test+ void openCypherQueryWorksOverBolt() {+ String createResponse = given()+ .header("Authorization", AUTH)+ .contentType(FORM)+ .formParam("Action", "CreateDBCluster")+ .formParam("DBClusterIdentifier", CLUSTER_ID)+ .formParam("Engine", "neptune")+ .when().post("/")+ .then()+ .statusCode(200)+ .extract().asString();++ int boltPort = parsePort(createResponse);++ try (Driver driver = GraphDatabase.driver(+ "bolt://localhost:" + boltPort, AuthTokens.none())) {+ driver.verifyConnectivity();+ try (Session session = driver.session()) {+ long one = session.run("RETURN 1 AS n").single().get("n").asLong();+ assertEquals(1L, one, "openCypher RETURN should evaluate on the neo4j backend");++ session.run("CREATE (:Person {name: 'Alice'})").consume();+ long count = session.run("MATCH (p:Person) RETURN count(p) AS c")+ .single().get("c").asLong();+ assertEquals(1L, count, "openCypher CREATE + MATCH should round-trip");+ }+ } finally {+ given()+ .header("Authorization", AUTH)+ .contentType(FORM)+ .formParam("Action", "DeleteDBCluster")+ .formParam("DBClusterIdentifier", CLUSTER_ID)+ .when().post("/")+ .then()+ .statusCode(200);+ }+ }++ private static int parsePort(String xml) {+ Matcher m = PORT.matcher(xml);+ if (!m.find()) {+ throw new AssertionError("No <Port> in CreateDBCluster response: " + xml);+ }+ return Integer.parseInt(m.group(1));+ }++ public static final class Neo4jDbTypeProfile implements QuarkusTestProfile {+ @Override+ public Map<String, String> getConfigOverrides() {+ return Map.of("floci.services.neptune.db-type", "neo4j");+ }+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbTypeTest.java b/src/test/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbTypeTest.javanew file mode 100644index 0000000000..27120e1a66--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/neptune/model/NeptuneDbTypeTest.java@@ -0,0 +1,43 @@+package io.github.hectorvent.floci.services.neptune.model;++import org.junit.jupiter.api.Test;++import java.util.Optional;++import static org.junit.jupiter.api.Assertions.assertEquals;++class NeptuneDbTypeTest {++ @Test+ void defaultsToGremlinWhenUnset() {+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig(null));+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig(""));+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig(" "));+ }++ @Test+ void parsesGremlinAliases() {+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig("gremlin"));+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig("TinkerPop"));+ assertEquals(Optional.of(NeptuneDbType.GREMLIN), NeptuneDbType.fromConfig(" GREMLIN "));+ }++ @Test+ void parsesNeo4jAliases() {+ assertEquals(Optional.of(NeptuneDbType.NEO4J), NeptuneDbType.fromConfig("neo4j"));+ assertEquals(Optional.of(NeptuneDbType.NEO4J), NeptuneDbType.fromConfig("openCypher"));+ assertEquals(Optional.of(NeptuneDbType.NEO4J), NeptuneDbType.fromConfig("cypher"));+ assertEquals(Optional.of(NeptuneDbType.NEO4J), NeptuneDbType.fromConfig("bolt"));+ }++ @Test+ void backendPortsMatchProtocols() {+ assertEquals(8182, NeptuneDbType.GREMLIN.backendPort());+ assertEquals(7687, NeptuneDbType.NEO4J.backendPort());+ }++ @Test+ void rejectsUnknownDbType() {+ assertEquals(Optional.empty(), NeptuneDbType.fromConfig("sparql"));+ }+}