Support distinct null and absent payload properties (#3646)

To support PATCH-style API semantics, we need to be able to distinguish between
a payload property being absent from the incoming JSON (in which case the existing
value should be left as is) and the property being present with a value of `null`
(in which case the client is asking us to remove the existing value).

Jackson supports using the Java `Optional` class to distinguish those two cases,
but it's a little cumbersome out of the box; add an extension method to simplify
using it for PATCH-style operations.

The distinction between "not required" and "can be null" needs to be reflected
in the OpenAPI schema as well. We could do it by adding `@Schema(nullable = true)`
to payload properties, but that'll add a lot of noise, so instead add logic to
automatically mark all `Optional` payload properties as allowing null values.

Author: sgrimm

src/main/kotlin/com/terraformation/backend/api/OpenApiConfig.kt

@@ -18,14 +18,17 @@ import io.swagger.v3.oas.models.media.StringSchema
 import io.swagger.v3.oas.models.security.SecurityScheme
 import jakarta.inject.Named
 import java.time.ZoneId
+import java.util.Optional
 import kotlin.reflect.KClass
 import kotlin.reflect.full.createType
 import kotlin.reflect.full.declaredMemberProperties
 import kotlin.reflect.full.findAnnotation
+import kotlin.reflect.full.isSubclassOf
 import kotlin.reflect.full.isSubtypeOf
 import kotlin.reflect.full.primaryConstructor
 import kotlin.reflect.full.superclasses
 import kotlin.reflect.jvm.javaField
+import kotlin.reflect.jvm.jvmErasure
 import kotlin.reflect.typeOf
 import org.jooq.DSLContext
 import org.springdoc.core.customizers.OpenApiCustomizer
@@ -157,6 +160,13 @@ class OpenApiConfig(private val keycloakInfo: KeycloakInfo) : OpenApiCustomizer
           if (propertySchema is ArraySchema && propertySchema.items is MapSchema) {
             propertySchema.items.additionalProperties = true
           }
+
+          // Optional<*> properties should be marked as nullable in the schema.
+          if (
+              propertySchema != null && property.returnType.jvmErasure.isSubclassOf(Optional::class)
+          ) {
+            propertySchema.nullable = true
+          }
         }
       }
     }

src/main/kotlin/com/terraformation/backend/util/Extensions.kt

@@ -13,6 +13,7 @@ import java.time.LocalDate
 import java.time.LocalTime
 import java.time.ZoneId
 import java.time.ZonedDateTime
+import java.util.Optional
 import org.geotools.api.referencing.FactoryException
 import org.geotools.api.referencing.crs.CoordinateReferenceSystem
 import org.geotools.geometry.jts.JTS
@@ -248,3 +249,39 @@ fun Geometry.nearlyCoveredBy(other: Geometry, minCoveragePercent: Double = 99.99
  */
 fun Geometry.differenceNullable(other: Geometry?): Geometry =
     if (other != null) difference(other) else this
+
+/**
+ * Applies this `Optional` as a replacement for an existing value.
+ *
+ * This is primarily used with payloads for `PATCH` endpoints that can update nullable values. For
+ * example, say an entity has a property `notes` of type `String?`. We'd want to handle a `PATCH`
+ * request as follows:
+ *
+ * | JSON               | Desired end result      |
+ * |--------------------|-------------------------|
+ * | `{}`               | Keep the original notes |
+ * | `{"notes": null}`  | Set notes to null       |
+ * | `{"notes": "bar"}` | Set notes to "bar"      |
+ *
+ * If a payload class includes `notes: Optional<String>?`, Jackson (with the JDK8 module enabled)
+ * deserializes it as follows:
+ *
+ * | JSON               | Deserializes to              |
+ * |--------------------|------------------------------|
+ * | `{}`               | `notes = null`               |
+ * | `{"notes": null}`  | `notes = Optional.empty()`   |
+ * | `{"notes": "bar"}` | `notes = Optional.of("bar")` |
+ *
+ * This method implements the patch semantics from the first table. Use it like this:
+ * ```kotlin
+ * val updatedModel = model.copy(
+ *     notes = payload.notes.patchNullable(model.notes),
+ * )
+ * ```
+ *
+ * Updates to non-nullable values can be handled by making the PATCH request payload fields nullable
+ * and using `payloadField ?: originalValue`; Jackson will set the payload field to null if it's
+ * absent. This will have the effect of silently ignoring attempts to set non-nullable values to
+ * null, which should be acceptable in most cases.
+ */
+fun <T> Optional<T>?.patchNullable(original: T?): T? = if (this == null) original else orElse(null)