Document exceptions [and/or do the detailed I/O rework]

[tcoopman]

For example, Dream.send might fail if the socket is not connected anymore. I believe it would be useful if these exceptions are documented in the API reference.

[aantron]

Agreed, thanks.

[aantron]

Also leaving a note to myself to document more clearly Dream's "philosophy" about exceptions.

For the time being, I'll sketch it here. Dream prefers encoding errors that can be caused by the client in types (option, result), and programming errors (like trying to access a path parameter that was not defined in your route) as exceptions.

Closed WebSockets are debatable, since I think Dream currently offers no good way to know if the socket was closed by the client, besides the exception itself.

There will be some reworks of "side" information flow (like sockets closing) in the future, hopefully without touching the main "data" API too much.

[tcoopman]

Closed WebSockets are debatable, since I think Dream currently offers no good way to know if the socket was closed by the client, besides the exception itself.

I agree, that's something I want to partly try to address in what I'm implementing at the moment (#75) where I would like to have a heartbeat in both directions. So there is at least some way of knowing when a client has lost the connection / closed (and maybe offer reconnection possibilities)