Add section on SignalR MessagePack "known issues" #11170
Conversation
There are some known issues/quirks in the MessagePack Hub Protocol for SignalR. We should call them out in our docs instead of making users search GitHub for these answers :)
analogrelay
requested review from
halter73,
mikaelm12,
BrennanConroy and
scottaddie
| @@ -94,6 +94,64 @@ const connection = new signalR.HubConnectionBuilder() | |||
| > [!NOTE] | |||
| > At this time, there are no configuration options for the MessagePack protocol on the JavaScript client. | |||
|
|
|||
| ## MessagePack Quirks | |||
There was a problem hiding this comment.
Not sure "quirks" is the right name here... very open to suggestions. I hestitate to use "Known Issues" because that (to me) implies that we're going to work on fixing them, which we aren't. I started with "Differences between MessagePack and JSON serialization" but some of these aren't exactly "differences" between JSON and MessagePack, they're just notable things for MessagePack (AOT support, for example didn't feel like a "difference"... though it kind of is... 🤷♂️).
There was a problem hiding this comment.
I think "quirks" describes it well.
There was a problem hiding this comment.
Use sentence casing for headings. For example, "MessagePack quirks".
There was a problem hiding this comment.
Cool, wasn't sure if there's a translation concern around using a word like "quirks". I'll update the casing.
|
|
||
| ### DateTime.MinValue is not supported by MessagePack in JavaScript | ||
|
|
||
| The [msgpack5](https://github.com/mcollina/msgpack5) library used by the SignalR JavaScript client does not support the `timestamp96` type in MessagePack. This type is used to encode very large date values (either very early in the past or very far in the future). The value of `DateTime.MinValue` is `January 1, 0001` which must be encoded in a `timestamp96` value. Because of this, sending `DateTime.MinValue` to a JavaScript client is not supported. Usually, `DateTime.MinValue` is used to encode a "missing" or `null` value. If you need to encode that value in MessagePack, use a nullable `DateTime` value (`DateTime?`) or encode a separate `bool` value indicating if the date is present. |
There was a problem hiding this comment.
Because of this, sending
DateTime.MinValueto a JavaScript client is not supported.
If I tried to send DateTime.MinValue to the JS client with MessagePack, what would happen?
There was a problem hiding this comment.
Exception shows up in the JS console:
Uncaught Error: unable to find ext type 255 at decoder.js:427
at h (decoder.js:427)
at l (decoder.js:263)
at d (decoder.js:358)
at l (decoder.js:243)
at u (decoder.js:335)
at l (decoder.js:285)
at u (decoder.js:335)
at l (decoder.js:285)
at u (decoder.js:335)
at l (decoder.js:285)
There was a problem hiding this comment.
I could include that text in the doc for google-fu
|
|
||
| The [msgpack5](https://github.com/mcollina/msgpack5) library used by the SignalR JavaScript client does not support the `timestamp96` type in MessagePack. This type is used to encode very large date values (either very early in the past or very far in the future). The value of `DateTime.MinValue` is `January 1, 0001` which must be encoded in a `timestamp96` value. Because of this, sending `DateTime.MinValue` to a JavaScript client is not supported. Usually, `DateTime.MinValue` is used to encode a "missing" or `null` value. If you need to encode that value in MessagePack, use a nullable `DateTime` value (`DateTime?`) or encode a separate `bool` value indicating if the date is present. | ||
|
|
||
| See [aspnet/SignalR#2228](https://github.com/aspnet/SignalR/issues/2228) for more information on this limitation. |
There was a problem hiding this comment.
Is it recommended to link to GitHub issues for complex topics? Maybe the prose should mention this is a GitHub issue incase some peopled don't recognize the "aspnet/SignalR#2228" GitHub link syntax.
We should probably make sure the issue is locked before linking to it in docs, but it doesn't matter in this particular case, since aspnet/SignalR is archived.
There was a problem hiding this comment.
Yeah, I'm not sure either. I'm happy to remove it but I thought it might be worth including the link to the issue for more context. Agreed that we can make it clearer that it's an issue link.
| @@ -94,6 +94,64 @@ const connection = new signalR.HubConnectionBuilder() | |||
| > [!NOTE] | |||
| > At this time, there are no configuration options for the MessagePack protocol on the JavaScript client. | |||
|
|
|||
| ## MessagePack Quirks | |||
There was a problem hiding this comment.
Use sentence casing for headings. For example, "MessagePack quirks".
Co-Authored-By: anurse <[email protected]>
Co-Authored-By: anurse <[email protected]>
There are some known issues/quirks in the MessagePack Hub Protocol for SignalR. We should call them out in our docs instead of making users search GitHub for these answers :).
Internal Review Version