[DEVEX-222] - Auto serialization feedback improvements (#338)

* [DEVEX-222] Fixed the missing application of custom serialization setting in AppendToStreamAsync method

* [DEVEX-222] Added stream state as a mandatory parameter in append to stream

Added also override for raw event append that has options and made other methods obsolete.

Introduced OperationOptions that compose default client operation settings plus credentials and deadlines.

* [DEVEX-222] Ensured that metadata is serialized with auto-serialization as regular system metadata

* [DEVEX-222] Adjusted samples to match the append api changes

Added also factor for event data that's not requiring to provide id immediately

* [DEVEX-222] Added MessageData type as an easier to use replacement for EventData, and better aligned with general usage of messages instead of just events

* [DEVEX-222] Refactored setting stream metadata to use OperationOptions

* [DEVEX-222] Added DeserializedData and DeserializedMessages extensions for read results

That should be a middle ground without forcing people to use a regular ResolvedEvent if they don't want to

* [DEVEX-222] Simplified the message serializer implementation

Now serializer creates a derived serializer merging operation settings with default settings if needed. That allowed to hide internal details and there's no need to pass content type explicitly, as it's already in settings.

Extended SchemaRegistry to provide wrapper methods to naming resolution context. Thanks to that MessageSerializer doesn't need to reference it internally.

To make responsibilities clearer made also naming resolution context part of serializer context.

* [DEVEX-222] Marked old Stream Metadata options as obsolete

* [DEVEX-222] Made old Read methods obsolete and used the new ones in tests

* [DEVEX-222] Made Read options nullable, to precisely know if user provided options or not

* [DEVEX-222] Made the Read Options nullable and thanks to that smarter, so e.g. FromEnd assigns also backwards if it wasn't set

* [DEVEX-222] Made old SetStreamMetadata and ConditionalAppend methods obsolete

* [DEVEX-222] Added delete method with options

* [DEVEX-222] Made old subscription methods obsolete and adjusted tests to use them

* [DEVEX-222] Added Tombstone method with options and made the old obsolete

* [DEVEX-222] Made all persistent subscription methods obsolete

* [DEVEX-222] Added samples showcasing auto-serialization usage

* [DEVEX-222] Reshaped type resolution strategy to take EventRecord instead of just raw string.

That should enable current users to override their strategy if they used something more than just message type name from EventRecord.

It needs to be EventRecord and not ResolvedEvent, as resolution happens before creating ResolvedEvent.

* [DEVEX-222] Changed message type registration to allow multiple message type names mapping to the same CLR class

* [DEVEX-222] Nested Message type mapping into settings object

* [DEVEX-222] Added nested message type mapping

* [DEVEX-222] Replaced clr type with clr type name in naming resolution

Tha makes naming strategy focused on just mapping types back and forth and allowing to disable auto registration

Author: oskardudycz

samples/appending-events/Program.cs

@@ -1,6 +1,4 @@
-using KurrentDB.Client;
-
-#pragma warning disable CS8321 // Local function is declared but never used
+#pragma warning disable CS8321 // Local function is declared but never used
 
 var settings = KurrentDBClientSettings.Create("esdb://localhost:2113?tls=false");
 
@@ -9,91 +7,155 @@
 await using var client = new KurrentDBClient(settings);
 
 await AppendToStream(client);
+await AppendToStreamWithAutoSerialization(client);
+await AppendToStreamWithMetadataAndAutoSerialization(client);
 await AppendWithConcurrencyCheck(client);
 await AppendWithNoStream(client);
 await AppendWithSameId(client);
+await AppendWithSameIdAndAutoSerialization(client);
 
 return;
 
 static async Task AppendToStream(KurrentDBClient client) {
 	#region append-to-stream
 
-	var eventData = new EventData(
-		Uuid.NewUuid(),
+	var eventData = MessageData.From(
 		"some-event",
 		"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray()
 	);
 
 	await client.AppendToStreamAsync(
 		"some-stream",
 		StreamState.NoStream,
-		new List<EventData> {
-			eventData
-		}
+		[eventData]
 	);
 
 	#endregion append-to-stream
 }
 
+static async Task AppendToStreamWithAutoSerialization(KurrentDBClient client) {
+	#region append-to-stream-with-auto-serialization
+
+	var shoppingCartId = Guid.NewGuid();
+
+	var @event = new ProductItemAddedToShoppingCart(
+		shoppingCartId,
+		new PricedProductItem("t-shirt", 1, 99.99m)
+	);
+
+	await client.AppendToStreamAsync(
+		$"shopping_cart-{shoppingCartId}",
+		StreamState.NoStream,
+		[@event]
+	);
+
+	#endregion append-to-stream-with-auto-serialization
+}
+
+static async Task AppendToStreamWithMetadataAndAutoSerialization(KurrentDBClient client) {
+	#region append-to-stream-with-metadata-and-auto-serialization
+
+	var shoppingCartId = Guid.NewGuid();
+	var clientId       = Guid.NewGuid().ToString();
+
+	var @event = new ProductItemAddedToShoppingCart(
+		shoppingCartId,
+		new PricedProductItem("t-shirt", 1, 99.99m)
+	);
+
+	var metadata = new ShoppingCartMetadata(clientId);
+
+	var message = Message.From(@event, metadata);
+
+	await client.AppendToStreamAsync(
+		$"shopping_cart-{shoppingCartId}",
+		StreamState.NoStream,
+		[message]
+	);
+
+	#endregion append-to-stream-with-metadata-and-auto-serialization
+}
+
 static async Task AppendWithSameId(KurrentDBClient client) {
 	#region append-duplicate-event
 
-	var eventData = new EventData(
-		Uuid.NewUuid(),
+	var eventData = MessageData.From(
 		"some-event",
-		"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray()
+		"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray(),
+		messageId: Uuid.NewUuid()
 	);
 
 	await client.AppendToStreamAsync(
 		"same-event-stream",
 		StreamState.Any,
-		new List<EventData> {
-			eventData
-		}
+		[eventData]
 	);
 
 	// attempt to append the same event again
 	await client.AppendToStreamAsync(
 		"same-event-stream",
 		StreamState.Any,
-		new List<EventData> {
-			eventData
-		}
+		[eventData]
 	);
 
 	#endregion append-duplicate-event
 }
 
+static async Task AppendWithSameIdAndAutoSerialization(KurrentDBClient client) {
+	#region append-duplicate-event-with-serialization
+
+	var shoppingCartId = Guid.NewGuid();
+
+	var @event = new ProductItemAddedToShoppingCart(
+		shoppingCartId,
+		new PricedProductItem("t-shirt", 1, 99.99m)
+	);
+
+	var message = Message.From(
+		@event,
+		messageId: Uuid.NewUuid()
+	);
+
+	await client.AppendToStreamAsync(
+		"same-event-stream",
+		StreamState.Any,
+		[message]
+	);
+
+	// attempt to append the same event again
+	await client.AppendToStreamAsync(
+		"same-event-stream",
+		StreamState.Any,
+		[message]
+	);
+
+	#endregion append-duplicate-event-with-serialization
+}
+
 static async Task AppendWithNoStream(KurrentDBClient client) {
 	#region append-with-no-stream
 
-	var eventDataOne = new EventData(
-		Uuid.NewUuid(),
+	var eventDataOne = MessageData.From(
 		"some-event",
 		"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray()
 	);
 
-	var eventDataTwo = new EventData(
-		Uuid.NewUuid(),
+	var eventDataTwo = MessageData.From(
 		"some-event",
 		"{\"id\": \"2\" \"value\": \"some other value\"}"u8.ToArray()
 	);
 
 	await client.AppendToStreamAsync(
 		"no-stream-stream",
 		StreamState.NoStream,
-		new List<EventData> {
-			eventDataOne
-		}
+		[eventDataOne]
 	);
 
 	// attempt to append the same event again
 	await client.AppendToStreamAsync(
 		"no-stream-stream",
 		StreamState.NoStream,
-		new List<EventData> {
-			eventDataTwo
-		}
+		[eventDataTwo]
 	);
 
 	#endregion append-with-no-stream
@@ -103,56 +165,45 @@ static async Task AppendWithConcurrencyCheck(KurrentDBClient client) {
 	await client.AppendToStreamAsync(
 		"concurrency-stream",
 		StreamState.Any,
-		new[] { new EventData(Uuid.NewUuid(), "-", ReadOnlyMemory<byte>.Empty) }
+		[MessageData.From("-", ReadOnlyMemory<byte>.Empty)]
 	);
 
 	#region append-with-concurrency-check
 
-	var clientOneRead = client.ReadStreamAsync(
-		Direction.Forwards,
-		"concurrency-stream",
-		StreamPosition.Start
-	);
+	var clientOneRead = client.ReadStreamAsync("concurrency-stream");
 
 	var clientOneRevision = (await clientOneRead.LastAsync()).Event.EventNumber.ToUInt64();
 
-	var clientTwoRead     = client.ReadStreamAsync(Direction.Forwards, "concurrency-stream", StreamPosition.Start);
+	var clientTwoRead     = client.ReadStreamAsync("concurrency-stream");
 	var clientTwoRevision = (await clientTwoRead.LastAsync()).Event.EventNumber.ToUInt64();
 
-	var clientOneData = new EventData(
-		Uuid.NewUuid(),
+	var clientOneData = MessageData.From(
 		"some-event",
 		"{\"id\": \"1\" \"value\": \"clientOne\"}"u8.ToArray()
 	);
 
 	await client.AppendToStreamAsync(
 		"no-stream-stream",
 		clientOneRevision,
-		new List<EventData> {
-			clientOneData
-		}
+		[clientOneData]
 	);
 
-	var clientTwoData = new EventData(
-		Uuid.NewUuid(),
+	var clientTwoData = MessageData.From(
 		"some-event",
 		"{\"id\": \"2\" \"value\": \"clientTwo\"}"u8.ToArray()
 	);
 
 	await client.AppendToStreamAsync(
 		"no-stream-stream",
 		clientTwoRevision,
-		new List<EventData> {
-			clientTwoData
-		}
+		[clientTwoData]
 	);
 
 	#endregion append-with-concurrency-check
 }
 
 static async Task AppendOverridingUserCredentials(KurrentDBClient client, CancellationToken cancellationToken) {
-	var eventData = new EventData(
-		Uuid.NewUuid(),
+	var eventData = MessageData.From(
 		"TestEvent",
 		"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray()
 	);
@@ -162,10 +213,23 @@ static async Task AppendOverridingUserCredentials(KurrentDBClient client, Cancel
 	await client.AppendToStreamAsync(
 		"some-stream",
 		StreamState.Any,
-		new[] { eventData },
-		userCredentials: new UserCredentials("admin", "changeit"),
-		cancellationToken: cancellationToken
+		[eventData],
+		new AppendToStreamOptions { UserCredentials = new UserCredentials("admin", "changeit") },
+		cancellationToken
 	);
 
 	#endregion overriding-user-credentials
 }
+
+public record PricedProductItem(
+	string ProductId,
+	int Quantity,
+	decimal UnitPrice
+);
+
+public record ProductItemAddedToShoppingCart(
+	Guid CartId,
+	PricedProductItem ProductItem
+);
+
+public record ShoppingCartMetadata(string ClientId);

samples/diagnostics/Program.cs

@@ -55,18 +55,15 @@ static async Task TraceAppendToStream(KurrentDBClient client) {
 
 		host.Start();
 
-		var eventData = new EventData(
-			Uuid.NewUuid(),
+		var eventData = MessageData.From(
 			"some-event",
 			"{\"id\": \"1\" \"value\": \"some value\"}"u8.ToArray()
 		);
 
 		await client.AppendToStreamAsync(
 			Uuid.NewUuid().ToString(),
 			StreamState.Any,
-			new List<EventData> {
-				eventData
-			}
+			[eventData]
 		);
 
 		# endregion setup-client-for-tracing

samples/projection-management/Program.cs

@@ -439,8 +439,7 @@ static async Task Populate(string connection, int numberOfEvents) {
 	var client = new KurrentDBClient(settings);
 	var messages = Enumerable.Range(0, numberOfEvents).Select(
 		number =>
-			new EventData(
-				Uuid.NewUuid(),
+			MessageData.From(
 				"eventtype",
 				Encoding.UTF8.GetBytes($@"{{ ""Id"":{number} }}")
 			)

samples/quick-start/Program.cs

@@ -1,7 +1,4 @@
-using System.Text.Json;
-using KurrentDB.Client;
-
-var tokenSource       = new CancellationTokenSource();
+var tokenSource       = new CancellationTokenSource();
 var cancellationToken = tokenSource.Token;
 
 #region createClient
@@ -21,20 +18,14 @@
 	ImportantData = "I wrote my first event!"
 };
 
-var eventData = new EventData(
-	Uuid.NewUuid(),
-	"TestEvent",
-	JsonSerializer.SerializeToUtf8Bytes(evt)
-);
-
 #endregion createEvent
 
 #region appendEvents
 
 await client.AppendToStreamAsync(
 	"some-stream",
 	StreamState.Any,
-	new[] { eventData },
+	[evt],
 	cancellationToken: cancellationToken
 );
 
@@ -45,23 +36,23 @@ await client.AppendToStreamAsync(
 await client.AppendToStreamAsync(
 	"some-stream",
 	StreamState.Any,
-	new[] { eventData },
-	userCredentials: new UserCredentials("admin", "changeit"),
-	cancellationToken: cancellationToken
+	[evt],
+	new AppendToStreamOptions { UserCredentials = new UserCredentials("admin", "changeit") },
+	cancellationToken
 );
 
 #endregion overriding-user-credentials
 
 #region readStream
 
 var result = client.ReadStreamAsync(
-	Direction.Forwards,
 	"some-stream",
-	StreamPosition.Start,
 	cancellationToken: cancellationToken
 );
 
-var events = await result.ToListAsync(cancellationToken);
+var events = await result
+	.DeserializedData()
+	.ToListAsync(cancellationToken);
 
 #endregion readStream