Introduce RequestResponseConverter and make all non-generated JsonConverters public

Author: flobernd

docs/reference/source-serialization.md

@@ -8,7 +8,13 @@ mapped_pages:
 Source serialization refers to the process of (de)serializing POCO types in consumer applications as source documents indexed and retrieved from {{es}}. A source serializer implementation handles serialization, with the default implementation using the `System.Text.Json` library. As a result, you may use `System.Text.Json` attributes and converters to control the serialization behavior.
 
 - [Modelling documents with types](#modeling-documents-with-types)
+  - [Default behavior](#default-behaviour)
+  - [Using Elasticsearch types in documents](#elasticsearch-types-in-documents)
 - [Customizing source serialization](#customizing-source-serialization)
+  - [Using `System.Text.Json` attributes](#system-text-json-attributes)
+  - [Configuring custom `JsonSerializerOptions`](#configuring-custom-jsonserializeroptions)
+  - [Registering custom `System.Text.Json` converters](#registering-custom-converters)
+  - [Creating a custom `Serializer`](#creating-custom-serializers)
 - [Native AOT](#native-aot)
 
 ## Modeling documents with types [modeling-documents-with-types]
@@ -51,6 +57,34 @@ The index request is serialized, with the source serializer handling the `MyDocu
 }
 ```
 
+### Using Elasticsearch types in documents [elasticsearch-types-in-documents]
+
+There are various cases where you might have a POCO type that contains an `Elastic.Clients.Elasticsearch` type as one of its properties.
+
+For example, consider if you want to use percolation; you need to store {{es}} queries as part of the `_source` of your document, which means you need to have a POCO that looks like this:
+
+```csharp
+using Elastic.Clients.Elasticsearch.QueryDsl;
+using Elastic.Clients.Elasticsearch.Serialization;
+
+public class MyPercolationDocument
+{
+    [JsonConverter(typeof(RequestResponseConverter<Query>))] <2>
+    public Query Query { get; set; } <2>
+
+    public string Category { get; set; }
+}
+```
+
+1. The `Query` property uses the `Elastic.Clients.Elasticsearch.QueryDsl.Query` Elasticsearch type.
+2. The `JsonConverter` attribute specifies the `RequestResponseConverter<T>` to be used for the `Query` property. This special converter instructs the `DefaultSourceSerializer` to delegate (de-)serialization to the `RequestResponseSerializer`.
+
+::::{warning}
+
+Failure to strictly use `RequestResponseConverter<T>` for `Elastic.Clients.Elasticsearch` types will most likely result in problems with document (de-)serialization.
+
+::::
+
 ## Customizing source serialization [customizing-source-serialization]
 
 The built-in source serializer handles most POCO document models correctly. Sometimes, you may need further control over how your types are serialized.
@@ -348,14 +382,17 @@ var client = new ElasticsearchClient(settings);
 
 1. If implementing `Serializer` is enough, why must we provide an instance wrapped in a factory `Func`?
 
-There are various cases where you might have a POCO type that contains an `Elastic.Clients.Elasticsearch` type as one of its properties. The `SourceSerializerFactory` delegate provides access to the default built-in serializer so you can access it when necessary. For example, consider if you want to use percolation; you need to store {{es}} queries as part of the `_source` of your document, which means you need to have a POCO that looks like this.
+There are various cases where you might have a POCO type that contains an `Elastic.Clients.Elasticsearch` type as one of its properties (see [Elasticsearch types in documents](#elasticsearch-types-in-documents)). The `SourceSerializerFactory` delegate provides access to the default built-in serializer so you can access it when necessary. For example, consider if you want to use percolation; you need to store {{es}} queries as part of the `_source` of your document, which means you need to have a POCO that looks like this.
 
 ```csharp
 using Elastic.Clients.Elasticsearch.QueryDsl;
+using Elastic.Clients.Elasticsearch.Serialization;
 
 public class MyPercolationDocument
 {
+    [JsonConverter(typeof(RequestResponseConverter<Query>))]
     public Query Query { get; set; }
+
     public string Category { get; set; }
 }
 ```

src/Elastic.Clients.Elasticsearch/_Shared/Api/ResponseItem.cs

@@ -7,7 +7,7 @@
 
 namespace Elastic.Clients.Elasticsearch.Core.Bulk;
 
-[JsonConverter(typeof(BulkResponseItemConverter))]
+[JsonConverter(typeof(Json.BulkResponseItemConverter))]
 public abstract partial class ResponseItem
 {
 	public abstract string Operation { get; }

src/Elastic.Clients.Elasticsearch/_Shared/Api/SearchRequest.cs

@@ -4,7 +4,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Text.Json;
 using System.Text.Json.Serialization;
 
 using Elastic.Clients.Elasticsearch.Requests;
@@ -33,12 +32,12 @@ protected override (string ResolvedUrl, string UrlTemplate, Dictionary<string, s
 	}
 }
 
-[JsonConverter(typeof(SearchRequestOfTConverterFactory))]
+[JsonConverter(typeof(Json.SearchRequestOfTConverterFactory))]
 public partial class SearchRequest<TInferDocument> : SearchRequest
 {
 	static SearchRequest()
 	{
-		DynamicallyAccessed.PublicConstructors(typeof(SearchRequestOfTConverter<TInferDocument>));
+		DynamicallyAccessed.PublicConstructors(typeof(Json.SearchRequestOfTConverter<TInferDocument>));
 	}
 
 	public SearchRequest(Indices? indices) : base(indices)
@@ -61,29 +60,3 @@ public SearchRequestDescriptor<TDocument> Pit(string id, Action<Core.Search.Poin
 		return Pit(configure);
 	}
 }
-
-internal sealed class SearchRequestOfTConverterFactory :
-	JsonConverterFactory
-{
-	public override bool CanConvert(Type typeToConvert) =>
-		typeToConvert.IsGenericType && typeToConvert.GetGenericTypeDefinition() == typeof(SearchRequest<>);
-
-	public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options)
-	{
-		var args = typeToConvert.GetGenericArguments();
-
-#pragma warning disable IL3050
-		return (JsonConverter)Activator.CreateInstance(typeof(SearchRequestOfTConverter<>).MakeGenericType(args[0]));
-#pragma warning restore IL3050
-	}
-}
-
-internal sealed class SearchRequestOfTConverter<T> :
-	JsonConverter<SearchRequest<T>>
-{
-	public override SearchRequest<T>? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
-		throw new NotSupportedException();
-
-	public override void Write(Utf8JsonWriter writer, SearchRequest<T> value, JsonSerializerOptions options) =>
-		writer.WriteValue(options, (SearchRequest)value);
-}

src/Elastic.Clients.Elasticsearch/_Shared/Api/SearchRequestConverter.cs

@@ -0,0 +1,37 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+using Elastic.Clients.Elasticsearch.Serialization;
+
+namespace Elastic.Clients.Elasticsearch.Json;
+
+public sealed class SearchRequestOfTConverterFactory :
+	JsonConverterFactory
+{
+	public override bool CanConvert(Type typeToConvert) =>
+		typeToConvert.IsGenericType && typeToConvert.GetGenericTypeDefinition() == typeof(SearchRequest<>);
+
+	public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options)
+	{
+		var args = typeToConvert.GetGenericArguments();
+
+#pragma warning disable IL3050
+		return (JsonConverter)Activator.CreateInstance(typeof(SearchRequestOfTConverter<>).MakeGenericType(args[0]));
+#pragma warning restore IL3050
+	}
+}
+
+public sealed class SearchRequestOfTConverter<T> :
+	JsonConverter<SearchRequest<T>>
+{
+	public override SearchRequest<T>? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+		throw new NotSupportedException();
+
+	public override void Write(Utf8JsonWriter writer, SearchRequest<T> value, JsonSerializerOptions options) =>
+		writer.WriteValue(options, (SearchRequest)value);
+}

src/Elastic.Clients.Elasticsearch/_Shared/Core/DateTime/DateMath/DateMath.cs

@@ -6,13 +6,12 @@
 using System.Collections.Generic;
 using System.Globalization;
 using System.Text;
-using System.Text.Json;
 using System.Text.Json.Serialization;
 using System.Text.RegularExpressions;
 
 namespace Elastic.Clients.Elasticsearch;
 
-[JsonConverter(typeof(DateMathConverter))]
+[JsonConverter(typeof(Json.DateMathConverter))]
 public abstract class DateMath
 {
 	private static readonly Regex DateMathRegex =
@@ -174,26 +173,3 @@ private static void AppendTwoDigitNumber(StringBuilder result, int val)
 		result.Append((char)('0' + (val % 10)));
 	}
 }
-
-internal sealed class DateMathConverter : JsonConverter<DateMath>
-{
-	public override DateMath? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
-	{
-		if (reader.TokenType != JsonTokenType.String)
-			return null;
-
-		// TODO: Performance - Review potential to avoid allocation on DateTime path and use Span<byte>
-
-		var value = reader.GetString();
-
-		if (!value.Contains("|") && DateTime.TryParse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var dateTime))
-			return DateMath.Anchored(dateTime);
-
-		return DateMath.Anchored(value);
-	}
-
-	public override void Write(Utf8JsonWriter writer, DateMath value, JsonSerializerOptions options)
-	{
-		writer.WriteStringValue(value.ToString());
-	}
-}

src/Elastic.Clients.Elasticsearch/_Shared/Core/DateTime/DateMath/DateMathConverter.cs

@@ -0,0 +1,33 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Globalization;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Elastic.Clients.Elasticsearch.Json;
+
+public sealed class DateMathConverter : JsonConverter<DateMath>
+{
+	public override DateMath? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+	{
+		if (reader.TokenType != JsonTokenType.String)
+			return null;
+
+		// TODO: Performance - Review potential to avoid allocation on DateTime path and use Span<byte>
+
+		var value = reader.GetString();
+
+		if (!value.Contains("|") && DateTime.TryParse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var dateTime))
+			return DateMath.Anchored(dateTime);
+
+		return DateMath.Anchored(value);
+	}
+
+	public override void Write(Utf8JsonWriter writer, DateMath value, JsonSerializerOptions options)
+	{
+		writer.WriteStringValue(value.ToString());
+	}
+}

src/Elastic.Clients.Elasticsearch/_Shared/Core/DateTime/DateMath/DateMathExpression.cs

@@ -3,18 +3,20 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
-using System.Globalization;
-using System.Text.Json;
 using System.Text.Json.Serialization;
 
 namespace Elastic.Clients.Elasticsearch;
 
-[JsonConverter(typeof(DateMathExpressionConverter))]
+[JsonConverter(typeof(Json.DateMathExpressionConverter))]
 public class DateMathExpression : DateMath
 {
-	public DateMathExpression(string anchor) : base(anchor) { }
+	public DateMathExpression(string anchor) : base(anchor)
+	{
+	}
 
-	public DateMathExpression(DateTime anchor) : base(anchor) { }
+	public DateMathExpression(DateTime anchor) : base(anchor)
+	{
+	}
 
 	public DateMathExpression(Union<DateTime, string> anchor, DateMathTime range, DateMathOperation operation)
 		: base(anchor, range, operation) { }
@@ -43,33 +45,3 @@ public DateMath RoundTo(DateMathTimeUnit round)
 		return this;
 	}
 }
-
-internal sealed class DateMathExpressionConverter : JsonConverter<DateMathExpression>
-{
-	public override DateMathExpression? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
-	{
-		if (reader.TokenType != JsonTokenType.String)
-			return null;
-
-		// TODO: Performance - Review potential to avoid allocation on DateTime path and use Span<byte>
-
-		var value = reader.GetString();
-		reader.Read();
-
-		if (!value.Contains("|") && DateTime.TryParse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var dateTime))
-			return DateMath.Anchored(dateTime);
-
-		return new DateMathExpression(value);
-	}
-
-	public override void Write(Utf8JsonWriter writer, DateMathExpression value, JsonSerializerOptions options)
-	{
-		if (value is null)
-		{
-			writer.WriteNullValue();
-			return;
-		}
-
-		writer.WriteStringValue(value.ToString());
-	}
-}

src/Elastic.Clients.Elasticsearch/_Shared/Core/DateTime/DateMath/DateMathExpressionConverter.cs

@@ -0,0 +1,40 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Globalization;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Elastic.Clients.Elasticsearch.Json;
+
+public sealed class DateMathExpressionConverter : JsonConverter<DateMathExpression>
+{
+	public override DateMathExpression? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+	{
+		if (reader.TokenType != JsonTokenType.String)
+			return null;
+
+		// TODO: Performance - Review potential to avoid allocation on DateTime path and use Span<byte>
+
+		var value = reader.GetString();
+		reader.Read();
+
+		if (!value.Contains("|") && DateTime.TryParse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var dateTime))
+			return DateMath.Anchored(dateTime);
+
+		return new DateMathExpression(value);
+	}
+
+	public override void Write(Utf8JsonWriter writer, DateMathExpression value, JsonSerializerOptions options)
+	{
+		if (value is null)
+		{
+			writer.WriteNullValue();
+			return;
+		}
+
+		writer.WriteStringValue(value.ToString());
+	}
+}