Binary serialization with MsgPack

[kerams]

Aiming to implement binary serialization of API responses using Message Pack.

Once complete, it should support the same types as Fable.Remoting.Json while offering better (de)serialization performance and smaller payloads.

Supported types

• [x] Records
  • Represented by an array (Message Pack arr) of the values of its properties
  • 1 byte (2 if the record has more than 15 properties) + the size of property values
• [x] Unions
  • Represented as a 2-element array, with the first element being the DU case tag and second the case's fields
  • Case fields are either in an array or a single value if the case has only one field (i.e. saving 1 byte for each Some of 'a)
  • 2-3 bytes + the size of case fields
• [x] String
  • Represented as str (UTF8 bytes)
  • 1-5 bytes (based on the length of UTF8 bytes) + UTF8 bytes themselves
• [x] Fable string enum
  • See above
• [x] Integers
  • Signed/unsigned bytes and ints
  • 1-9 bytes depending on how many bytes each value needs, meaning an int64 that is close to 0 will take up 1 byte while another int64 that is larger than int32's range will consume 9 bytes
• [x] Bigint
  • Represented as bin
  • 1-5 bytes (based on how many bytes ToByteArray returns) + the bytes themselves
• [x] Floats
  • 5 bytes for float32, 9 bytes for float (Double) and decimals
• [x] Enums
  • Represented as int64
  • 1-9 bytes depending on how large the enum value is
• [x] Units of measure
• [x] Bool
  • 1 byte
• [x] Null
  • 1 byte
• [x] DateTime(Offset)
  • DateTime represented as int64 ticks (1-9 bytes depending on how large the date time is)
  • DateTimeOffset represented as a 2-element array of int64 ticks and the offset in minutes (3-12 bytes depending on how large the date time and offset are)
• [x] TimeSpan
  • Represented as int64 ticks
  • 1-9 bytes depending on how large the value is
• [x] Map/Dictionary
  • Represented as map
  • 1-5 bytes (based on the number of key-value pairs) + the size of individual elements
• [x] Array
  • Represented as array
  • 1-5 bytes (based on the number of elements) + the size of individual elements
• [x] List
  • See above
• [x] Tuples
  • See above
• [x] Byte[]
  • Represented as bin
  • 1-5 bytes (based on the number of bytes in the array) + the array itself
• [x] Guid
  • Represented as bin
  • 18 bytes

TODO

• [x] Support all the required types
• [x] Loads more tests (client and .NET deserialization)
• [x] Performance optimizations (mainly caching in order to avoid constant reflection)
• [x] Having a project with benchmarks would be nice
• [x] Finalize the API
• [x] Docs
• [x] Figure out if it's better to write asynchronously directly to ctx.Response.Body as the response is being serialized or synchronously to a MemoryStream, dumping it to ctx.Response.Body at the end of serialization I've opted for the latter for the simple reason that the serialization code would be absolutely riddled with task/async CEs.

Anything I've missed?

[kerams]

@Zaid-Ajaj, I'm in sight of the finish line. Are you in favor of the proposed API? I.e. adding |> withBinarySerialization when creating the proxy and server handlers?

[Zaid-Ajaj]

It looks really amazing 😍 :heart: The API looks good too and especially easy to start using once people update their adapters to the new version.

The only thing that might be missing is checking whether Fable.Remoting.DotnetClient works like it should with the binary protocol which also uses Fable.Remoting.Json for the data transport

[kerams]

The only thing that might be missing is checking whether Fable.Remoting.DotnetClient works like it should with the binary protocol

Right, the same goes for Giraffe.

[kerams]

Do you have any experience with performance tests under Fable by any chance? I've done some benchmarks of deserialization on .NET, and while the results are not too bad, they won't reflect Javascript performance.

BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.329 (2004/?/20H1)
AMD Ryzen 7 3700X, 1 CPU, 16 logical and 8 physical cores
.NET Core SDK=5.0.100-preview.8.20351.5
  [Host]     : .NET Core 3.1.2 (CoreCLR 4.700.20.6602, CoreFX 4.700.20.6702), X64 RyuJIT DEBUG
  DefaultJob : .NET Core 3.1.2 (CoreCLR 4.700.20.6602, CoreFX 4.700.20.6702), X64 RyuJIT
  Job-SXWUEH : .NET Core 3.1.2 (CoreCLR 4.700.20.6602, CoreFX 4.700.20.6702), X64 RyuJIT

InvocationCount=1  

Type	Method	Job	UnrollFactor	Mean	Error	StdDev	Median	Gen 0	Gen 1	Gen 2	Allocated
Int64ArrayDeserialization	Json	DefaultJob	16	37.91 ms	0.131 ms	0.123 ms	37.92 ms	2000.0000	142.8571	71.4286	18.03 MB
Int64ArrayDeserialization	MsgPack	Job-VVPEKY	1	10.84 ms	0.151 ms	0.133 ms	10.88 ms	-	-	-	8.39 MB
Int64ArraySerialization	Json	DefaultJob	16	56.42 ms	0.649 ms	0.608 ms	56.19 ms	5000.0000	1000.0000	-	47.71 MB
Int64ArraySerialization	MsgPack	DefaultJob	16	15.21 ms	0.112 ms	0.104 ms	15.22 ms	359.3750	62.5000	62.5000	4.29 MB
IntMaybeMapDeserialization	Json	DefaultJob	16	705.69 ms	4.656 ms	3.888 ms	706.33 ms	35000.0000	9000.0000	-	286.04 MB
IntMaybeMapDeserialization	MsgPack	Job-VVPEKY	1	35.71 ms	0.710 ms	1.895 ms	34.74 ms	2000.0000	1000.0000	-	22.67 MB
IntMaybeMapSerialization	Json	DefaultJob	16	232.29 ms	0.547 ms	0.512 ms	232.40 ms	9000.0000	1000.0000	-	76.1 MB
IntMaybeMapSerialization	MsgPack	DefaultJob	16	15.16 ms	0.219 ms	0.205 ms	15.08 ms	984.3750	281.2500	31.2500	8.55 MB
RecursiveRecordDeserialization	Json	DefaultJob	16	1,045.86 ms	10.316 ms	9.649 ms	1,043.33 ms	55000.0000	12000.0000	-	438.84 MB
RecursiveRecordDeserialization	MsgPack	Job-VVPEKY	1	541.63 ms	3.090 ms	2.413 ms	540.80 ms	26000.0000	9000.0000	-	209.36 MB
RecursiveRecordSerialization	Json	DefaultJob	16	570.48 ms	5.563 ms	5.204 ms	569.12 ms	30000.0000	9000.0000	1000.0000	271.83 MB
RecursiveRecordSerialization	MsgPack	DefaultJob	16	518.65 ms	1.895 ms	1.680 ms	519.25 ms	19000.0000	-	-	173.21 MB

[Zaid-Ajaj]

while the results are not too bad

LOL, "not bad" you say?! These benchmarks are INSANE 🤯 🤯

Do you have any experience with performance tests under Fable by any chance?

A while ago, I made a Fable project to test perf improvements in SimpleJson that is actually a unit test project with Mocha. When you run the tests in there, mocha shows you how long the test took so you can use that as a way to benchmark. I know it is not as fully-featured as with the .NET way but it should work OK-ish.

I believe this PR is ready to go? 😉

[kerams]

I believe this PR is ready to go? 😉

Yeah. Would be great if you could make a prerelease so that I can dogfood it and fix any issues.

it is not as fully-featured

I see what you mean. Should be sufficient for some ballpark numbers though.

[Zaid-Ajaj]

Packages are up :rocket: 🚀 🚀

I didn't bother with a prerelease version, I trust the integration tests :smile: do you wanna give it a try before I tweet this awesomeness? :wink:

[kerams]

Trying it right now. I think the new Nuget package is missing the source files.

[Zaid-Ajaj]

Which one of them. the Fable.Remoting.Client?

Edit: I see the issue now, source files of Fable.Remoting.MsgPack weren't published. Fixes the issue, it should be good now if you update Fable.Remoting.Client from 6.0.0 to 6.0.1

[kerams]

Tried it on one API endpoint and so far so good, no errors :). Message Pack without compression appears to produce slightly larger messages than JSON + Brotli in some cases, but when I enable it, the former has the upper hand.

[Zaid-Ajaj]

Do you think we should add docs to ensure compression in enabled when using msgpack?

[kerams]

Not sure if it's strictly necessary if this is almost as good as JSON with compression while using fewer CPU cycles. Besides, it's a little complicated here since in ASP.NET compression is enabled based on MIME types and responses with Message Pack use octet-stream (just like static files that you don't want to compress, such as images). I suppose the MIME type could be changed to something else to allow for better compression control.