I'm assuming and defining the following:
1. XMPP failures (which can occur at the TCP, TLS, and XML/XMPP
layers (as a stream error or forbidden input)) are fatal; they will
distrupt the XMPP session.
2. All fatal failures should be thrown (or similar) by `session', or
any other function that might produce them.
3. Authentication failures that are not "XMPP failures" are not fatal.
They do not necessarily terminate the stream. For example, the
developer should be able to make another authentication attempt.
The `Session' object returned by `session' might be useful even if
the authentication fails.
4. We can (and should) use one single data type for fatal failures.
(Previously, both StreamFailure and TlsFailure was used.)
5. We can catch and rethrow/wrap IO exceptions in the context of the
Pontarius XMPP error system that we decide to use, making the error
system more intuitive, Haskell-like, and more straight-forward to
implement. Calling `error' may only be done in the case of a
program error (a bug).
6. A logging system will remove the need for many of the error types.
Only exceptions that seem likely to affect the flow of client
applications should be defined.
7. The authentication functions are prone to fatal XMPP failures in
addition to non-fatal authentication conditions. (Previously,
`AuthStreamFailure' was used to wrap these errors.)
I'm hereby suggesting (and implementing) the following:
`StreamFailure' and `TlsFailure' should be joined into `XmppFailure'.
`pullStanza' and the other Connection functions used to throw
`IOException', `StreamFailure' and `TlsFailure' exceptions. With this
patch, they have been converted to `StateT Connection IO (Either
XmppFailure a)' computations. They also catch (some) IOException
errors and wrap them in the new `XmppIOException' constructor.
`newSession' is now `IO (Either XmppFailure Session)' as well (being
capable of throwing IO exceptions).
Whether or not to continue to a) wrap `XmppFailure' failures in an
`AuthStreamFailure' equivalent, or, b) treat the authentication
functions just like the other functions that may result in failure
(Either XmppFailure a), depends on how Network.Xmpp.Connection.auth
will be used. Since the latter will make `auth' more consistent, as
well as remove the need for a wrapped (and special-case) "AuthFailure"
type, I have decided to give the "b" approach a try. (The drawback
being, of course, that authentication errors can not be accessed
through the use of ErrorT. Whether or not this might be a problem, I
don't really know at this point.) As the SASL code (and SaslM)
depended on `AuthStreamFailure', it remains for internal use, at least
for the time-being. `session' is now an ErrorT computation as well.
Some functions have been updated as hacks, but this will be changed if
we decide to move forward with this approach.
As mentioned in #pontarius, `Context' is simply a bunch of thread
management features, and users that want that can build their own on
top of the `Connection' layer. The benefit of hiding `Context' is that
it makes the API clearer, and significantly decreases the complexity
of the library.
As the `Basic' module is simply an interface to `Connection', it was
renamed to `Connection'. The old `Connection' module was moved to
`Connection_'.
Exported the types of the fields of `Connection' (such as
`ConnectionState' and `ConnectionHandle' (previously `HandleLike').
stopped wrapping passwd in a SaslM computation for the time-being
SaslHandler now takes password and does not take hostname
minor formatting and documentation changes
runSasl where-local
SaslElement moved to Sasl/Types.hs
add sAuthzid to XmppConnection
add sAuthzid to XmppConnection more work on sasl infrastructure
move more stuff from DigestMd5 to Common
more work on sasl infrastructure
Jon Kristensen
Philipp Balzarek
Jon Kristensen