Documentation of exceptions thrown

[lugehorsam]

Hello, we're big fans of the Ninja WebSockets library and wrote an adapter to expose WebSocket functionality to our users through our library.

One question that has often come up from our users is what types of exceptions they can expect to be surfaced from the library, and in what cases these exceptions fire. For example, looking through the code, there are potential exceptions related to streams, cancelled operations, cancelled tasks (a subset of cancelled operations), and more.

We can test this empirically and we know to some extent it may depend on the platform, but it would be great to get a word from the author on the general design of what exceptions are thrown and when.

[ninjasource]

Hi Luke, I'm glad you are finding Ninja WebSockets useful! My original intention was to put all custom exceptions thrown by this library in the Ninja.WebSockets.Exceptions folder but as you have pointed out there if potential for variation from platform to platform. Additionally, taking a look at the code I can see a few instances where I have caught an exception, added some information, and then thrown it as a basic Exception (with the original exception as an inner) which is not ideal if you are trying to test all failure modes explicitly. If this sort of thing is an issue I can look at making an update no problem.

As for testing, you can override the GetStream function of the WebSocketClientFactory and use a named pipe instead of a tcp stream if you wish to test the library itself more thoroughly.

[lugehorsam]

@ninjasource good to keep in mind. I think the ideal solution would be information organized roughly as follows:

Behavior	Exception Type
Socket cannot perform DNS	Socket Exception with code X
Server closed socket	Socket Exception with code Y
Socket handshake failed	Some other exception
User cancelled connect	OperationCanceledException
User cancelled receive	OperationCanceledException
...etc.

IMO a typed exception is better as you said, but I think what would be most valuable is just knowing what would be thrown when, since tracing it through the code can be error prone. Up to you how you want to convey the information and not trying to create a lot more work for you :)

[ninjasource]

Ok what I'll do is wrap the stream errors in a custom exception so they can be caught and put the real exception as the inner exception. Unfortunately I cannot control what exceptions the TcpStream throws but at least I can put them all in one box.

And perhaps look into a table like you suggested