feat(unknownType): add support for Bolt Unknown Type

injectives · injectives · commit ed518bb7d5ee · 2025-09-18T18:25:13.000+01:00
diff --git a/driver/clirr-ignored-differences.xml b/driver/clirr-ignored-differences.xml
@@ -935,4 +935,10 @@
         <differenceType>8001</differenceType>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/types/TypeSystem</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.types.Type UNSUPPORTED()</method>
+    </difference>
+
 </differences>
diff --git a/driver/src/main/java/org/neo4j/driver/Value.java b/driver/src/main/java/org/neo4j/driver/Value.java
@@ -42,6 +42,7 @@
 import org.neo4j.driver.types.Relationship;
 import org.neo4j.driver.types.Type;
 import org.neo4j.driver.types.TypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
 import org.neo4j.driver.types.Vector;
 import org.neo4j.driver.util.Immutable;
 import org.neo4j.driver.util.Preview;
@@ -684,6 +685,10 @@ public interface Value extends MapAccessor, MapAccessorWithDefaultValue {
      *             <td>{@link TypeSystem#VECTOR}</td>
      *             <td>{@link Vector}</td>
      *         </tr>
+     *         <tr>
+     *             <td>{@link TypeSystem#UNSUPPORTED}</td>
+     *             <td>{@link UnsupportedTypeData}</td>
+     *         </tr>
      *     </tbody>
      * </table>
      *
diff --git a/driver/src/main/java/org/neo4j/driver/Values.java b/driver/src/main/java/org/neo4j/driver/Values.java
@@ -67,6 +67,7 @@
 import org.neo4j.driver.internal.value.PointValue;
 import org.neo4j.driver.internal.value.StringValue;
 import org.neo4j.driver.internal.value.TimeValue;
+import org.neo4j.driver.internal.value.UnsupportedValue;
 import org.neo4j.driver.internal.value.VectorValue;
 import org.neo4j.driver.mapping.Property;
 import org.neo4j.driver.types.Entity;
@@ -77,6 +78,7 @@
 import org.neo4j.driver.types.Point;
 import org.neo4j.driver.types.Relationship;
 import org.neo4j.driver.types.TypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
 import org.neo4j.driver.types.Vector;
 import org.neo4j.driver.util.Preview;
 
@@ -182,6 +184,9 @@ public static Value value(Object value) {
         if (value instanceof Vector vector) {
             return value(vector);
         }
+        if (value instanceof UnsupportedTypeData) {
+            return value((UnsupportedTypeData) value);
+        }
 
         if (value instanceof List<?>) {
             return value((List<Object>) value);
@@ -1149,4 +1154,8 @@ private static Value vector(Object array) {
                     "Unsupported vector element type: " + array.getClass().getName());
         }
     }
+
+    private static Value value(UnsupportedTypeData unsupportedTypeData) {
+        return new UnsupportedValue(unsupportedTypeData);
+    }
 }
diff --git a/driver/src/main/java/org/neo4j/driver/internal/InternalUnsupportedTypeData.java b/driver/src/main/java/org/neo4j/driver/internal/InternalUnsupportedTypeData.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.internal;
+
+import java.util.Optional;
+import org.neo4j.driver.types.UnsupportedTypeData;
+
+public record InternalUnsupportedTypeData(String name, String minProtocolVersion, String messageValue)
+        implements UnsupportedTypeData {
+    @Override
+    public Optional<String> message() {
+        return Optional.ofNullable(messageValue);
+    }
+}
diff --git a/driver/src/main/java/org/neo4j/driver/internal/types/InternalTypeSystem.java b/driver/src/main/java/org/neo4j/driver/internal/types/InternalTypeSystem.java
@@ -36,6 +36,7 @@
 import static org.neo4j.driver.internal.types.TypeConstructor.RELATIONSHIP;
 import static org.neo4j.driver.internal.types.TypeConstructor.STRING;
 import static org.neo4j.driver.internal.types.TypeConstructor.TIME;
+import static org.neo4j.driver.internal.types.TypeConstructor.UNSUPPORTED;
 import static org.neo4j.driver.internal.types.TypeConstructor.VECTOR;
 
 import org.neo4j.driver.Value;
@@ -72,6 +73,7 @@ public class InternalTypeSystem implements TypeSystem {
     private final TypeRepresentation durationType = constructType(DURATION);
     private final TypeRepresentation nullType = constructType(NULL);
     private final TypeRepresentation vectorType = constructType(VECTOR);
+    private final TypeRepresentation unsupportedType = constructType(UNSUPPORTED);
 
     private InternalTypeSystem() {}
 
@@ -180,6 +182,11 @@ public Type VECTOR() {
         return vectorType;
     }
 
+    @Override
+    public Type UNSUPPORTED() {
+        return unsupportedType;
+    }
+
     private TypeRepresentation constructType(TypeConstructor tyCon) {
         return new TypeRepresentation(tyCon);
     }
diff --git a/driver/src/main/java/org/neo4j/driver/internal/types/TypeConstructor.java b/driver/src/main/java/org/neo4j/driver/internal/types/TypeConstructor.java
@@ -57,7 +57,8 @@ public boolean covers(Value value) {
     DATE_TIME,
     DURATION,
     NULL,
-    VECTOR;
+    VECTOR,
+    UNSUPPORTED;
 
     private static TypeConstructor typeConstructorOf(Value value) {
         return ((InternalValue) value).typeConstructor();
diff --git a/driver/src/main/java/org/neo4j/driver/internal/value/BoltValueFactory.java b/driver/src/main/java/org/neo4j/driver/internal/value/BoltValueFactory.java
@@ -29,16 +29,19 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import org.neo4j.bolt.connection.BoltProtocolVersion;
 import org.neo4j.bolt.connection.values.Node;
 import org.neo4j.bolt.connection.values.Path;
 import org.neo4j.bolt.connection.values.Relationship;
 import org.neo4j.bolt.connection.values.Segment;
+import org.neo4j.bolt.connection.values.Type;
 import org.neo4j.bolt.connection.values.Value;
 import org.neo4j.bolt.connection.values.ValueFactory;
 import org.neo4j.driver.Values;
 import org.neo4j.driver.internal.InternalNode;
 import org.neo4j.driver.internal.InternalPath;
 import org.neo4j.driver.internal.InternalRelationship;
+import org.neo4j.driver.internal.InternalUnsupportedTypeData;
 
 public class BoltValueFactory implements ValueFactory {
     private static final BoltValueFactory INSTANCE = new BoltValueFactory();
@@ -265,6 +268,15 @@ public Value vector(Class<?> elementType, Object elements) {
         return value;
     }
 
+    @Override
+    public Value unsupportedTypeData(String name, BoltProtocolVersion minBoltVersion, Map<String, Value> extra) {
+        var message = extra.get("message");
+        var messageString =
+                message != null ? message.boltValueType().equals(Type.STRING) ? message.asString() : null : null;
+        return (InternalValue)
+                Values.value((Object) new InternalUnsupportedTypeData(name, minBoltVersion.toString(), messageString));
+    }
+
     @Override
     public Value unsupportedDateTimeValue(DateTimeException e) {
         return new UnsupportedDateTimeValue(e);
diff --git a/driver/src/main/java/org/neo4j/driver/internal/value/UnsupportedValue.java b/driver/src/main/java/org/neo4j/driver/internal/value/UnsupportedValue.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.internal.value;
+
+import org.neo4j.driver.internal.types.InternalTypeSystem;
+import org.neo4j.driver.types.UnsupportedTypeData;
+
+public final class UnsupportedValue extends ObjectValueAdapter<UnsupportedTypeData> {
+    public UnsupportedValue(UnsupportedTypeData adapted) {
+        super(adapted);
+    }
+
+    @Override
+    public org.neo4j.bolt.connection.values.Type boltValueType() {
+        return org.neo4j.bolt.connection.values.Type.UNSUPPORTED;
+    }
+
+    @Override
+    public org.neo4j.driver.types.Type type() {
+        return InternalTypeSystem.TYPE_SYSTEM.UNSUPPORTED();
+    }
+
+    @Override
+    public <T> T as(Class<T> targetClass) {
+        if (targetClass.isAssignableFrom(UnsupportedTypeData.class)) {
+            return targetClass.cast(asObject());
+        }
+        return asMapped(targetClass);
+    }
+}
diff --git a/driver/src/main/java/org/neo4j/driver/types/TypeSystem.java b/driver/src/main/java/org/neo4j/driver/types/TypeSystem.java
@@ -164,4 +164,20 @@ static TypeSystem getDefault() {
      */
     @Preview(name = "Neo4j Vector")
     Type VECTOR();
+
+    /**
+     * Returns a {@link Type} instance representing an unknown type.
+     * <p>
+     * An unknown type may occur when a new type is introduced in the Neo4j server and the driver is connected over an
+     * older Bolt Protocol version that does not support this type. The {@link UnsupportedTypeData} object provides information
+     * about the unknown type and the {@link UnsupportedTypeData#minProtocolVersion()} needed to transmit it. However, the
+     * {@link UnsupportedTypeData} object itself requires at least Bolt Protocol 6.0.
+     * <p>
+     * Note that the unknown type MUST NOT be sent to the server.
+     *
+     * @return the type instance
+     * @since 6.0.0
+     * @see UnsupportedTypeData
+     */
+    Type UNSUPPORTED();
 }
diff --git a/driver/src/main/java/org/neo4j/driver/types/UnsupportedTypeData.java b/driver/src/main/java/org/neo4j/driver/types/UnsupportedTypeData.java
@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.types;
+
+import java.util.Optional;
+
+/**
+ * An object instance of {@link TypeSystem#UNSUPPORTED()} type.
+ * <p>
+ * This object contains information about the unknown type and the {@link #minProtocolVersion()} needed to transmit it.
+ * <p>
+ * Note that this object MUST NOT be sent to the server.
+ *
+ * @since 6.0.0
+ */
+public interface UnsupportedTypeData {
+    /**
+     * Returns the type name.
+     * @return the type name
+     */
+    String name();
+
+    /**
+     * The minimum Bolt Protocol version needed to transmit this type.
+     * @return the minimum Bolt Protocol version
+     */
+    String minProtocolVersion();
+
+    /**
+     * An optional message.
+     * @return the message
+     */
+    Optional<String> message();
+}
diff --git a/driver/src/test/java/org/neo4j/driver/integration/ObjectMappingIT.java b/driver/src/test/java/org/neo4j/driver/integration/ObjectMappingIT.java
@@ -48,12 +48,14 @@
 import org.neo4j.driver.internal.InternalPoint3D;
 import org.neo4j.driver.internal.InternalRecord;
 import org.neo4j.driver.internal.InternalRelationship;
+import org.neo4j.driver.internal.InternalUnsupportedTypeData;
 import org.neo4j.driver.internal.value.NodeValue;
 import org.neo4j.driver.internal.value.RelationshipValue;
 import org.neo4j.driver.mapping.Property;
 import org.neo4j.driver.types.Float64Vector;
 import org.neo4j.driver.types.IsoDuration;
 import org.neo4j.driver.types.Point;
+import org.neo4j.driver.types.UnsupportedTypeData;
 
 final class ObjectMappingIT {
     @ParameterizedTest
@@ -77,6 +79,7 @@ void shouldMapValue(Function<Map<String, Value>, ValueHolder> valueFunction) {
         var point2d = (Point) new InternalPoint2D(0, 0, 0);
         var point3d = (Point) new InternalPoint3D(0, 0, 0, 0);
         var vector = new InternalFloat64Vector(new double[] {0.0, 100.0});
+        var unsupportedTypeData = new InternalUnsupportedTypeData("name", "99.99", "message");
 
         var properties = Map.ofEntries(
                 Map.entry("string", Values.value(string)),
@@ -101,7 +104,8 @@ void shouldMapValue(Function<Map<String, Value>, ValueHolder> valueFunction) {
                 Map.entry("javaDuration", Values.value(javaDuration)),
                 Map.entry("point2d", Values.value(point2d)),
                 Map.entry("point3d", Values.value(point3d)),
-                Map.entry("vector", Values.value(vector)));
+                Map.entry("vector", Values.value(vector)),
+                Map.entry("unsupportedTypeData", Values.value(unsupportedTypeData)));
 
         // when
         var valueHolder = valueFunction.apply(properties);
@@ -125,6 +129,7 @@ void shouldMapValue(Function<Map<String, Value>, ValueHolder> valueFunction) {
         assertEquals(point2d, valueHolder.point2d());
         assertEquals(point3d, valueHolder.point3d());
         assertEquals(vector, valueHolder.vector());
+        assertEquals(unsupportedTypeData, valueHolder.unsupportedTypeData());
     }
 
     static Stream<Arguments> shouldMapValueArgs() {
@@ -167,7 +172,8 @@ public record ValueHolder(
             Duration javaDuration,
             Point point2d,
             Point point3d,
-            Float64Vector vector) {}
+            Float64Vector vector,
+            UnsupportedTypeData unsupportedTypeData) {}
 
     public record StringValueHolder(String string) {}
 
diff --git a/pom.xml b/pom.xml
@@ -34,7 +34,7 @@
     <maven.deploy.skip>true</maven.deploy.skip>
 
     <!-- Versions -->
-    <neo4j-bolt-connection-bom.version>8.4.0</neo4j-bolt-connection-bom.version>
+    <neo4j-bolt-connection-bom.version>9.0-SNAPSHOT</neo4j-bolt-connection-bom.version>
     <reactive-streams.version>1.0.4</reactive-streams.version>
     <!-- Please note that when updating this dependency -->
     <!-- (i.e. due to a security vulnerability or bug) that the -->
diff --git a/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/TestkitModule.java b/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/TestkitModule.java
@@ -40,6 +40,7 @@
 import neo4j.org.testkit.backend.messages.responses.serializer.TestkitRecordSerializer;
 import neo4j.org.testkit.backend.messages.responses.serializer.TestkitRelationshipValueSerializer;
 import neo4j.org.testkit.backend.messages.responses.serializer.TestkitTimeValueSerializer;
+import neo4j.org.testkit.backend.messages.responses.serializer.TestkitUnsupportedValueSerializer;
 import neo4j.org.testkit.backend.messages.responses.serializer.TestkitValueSerializer;
 import neo4j.org.testkit.backend.messages.responses.serializer.TestkitVectorSerializer;
 import org.neo4j.driver.Record;
@@ -55,6 +56,7 @@
 import org.neo4j.driver.internal.value.PathValue;
 import org.neo4j.driver.internal.value.RelationshipValue;
 import org.neo4j.driver.internal.value.TimeValue;
+import org.neo4j.driver.internal.value.UnsupportedValue;
 import org.neo4j.driver.internal.value.VectorValue;
 import org.neo4j.driver.types.IsoDuration;
 import org.neo4j.driver.types.Vector;
@@ -86,5 +88,6 @@ public TestkitModule() {
         this.addSerializer(PathValue.class, new TestkitPathValueSerializer());
         this.addSerializer(RelationshipValue.class, new TestkitRelationshipValueSerializer());
         this.addSerializer(VectorValue.class, new TestkitVectorSerializer());
+        this.addSerializer(UnsupportedValue.class, new TestkitUnsupportedValueSerializer());
     }
 }
diff --git a/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/requests/GetFeatures.java b/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/requests/GetFeatures.java
@@ -77,7 +77,8 @@ public class GetFeatures implements TestkitRequest {
             "Feature:API:Summary:GqlStatusObjects",
             "Feature:API:Driver:MaxConnectionLifetime",
             "Optimization:HomeDatabaseCache",
-            "Feature:Bolt:HandshakeManifestV1"));
+            "Feature:Bolt:HandshakeManifestV1",
+            "Feature:API:Type.UnknownType"));
 
     private static final Set<String> SYNC_FEATURES = new HashSet<>(Arrays.asList(
             "Feature:Bolt:3.0",
diff --git a/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/responses/serializer/TestkitUnsupportedValueSerializer.java b/testkit-backend/src/main/java/neo4j/org/testkit/backend/messages/responses/serializer/TestkitUnsupportedValueSerializer.java
