As mentioned in a previous patch, the `AuthFailure' type signals a
(non-fatal) SASL error condition. This is now reflected in the
documentation.
I went through the different constructors for the type, looking at how
they were produced (thrown) and whether or not that information were
useful for the application using Pontarius XMPP.
To begin, I conclude that `AuthStreamFailure' is only used internally.
It will probably be removed when the internal type signatures of the
Sasl package are changed to conform with the rest of the `Error'
computations of Pontarius XMPP.
`AuthFailure' is not thrown as far as I can see, but is only used for
the Error instance.
`AuthNoAcceptableMechanism' is thrown by `xmppSasl' when none of the
mechanisms offered by the server is specified as acceptable by the
client. It wraps the mechanisms offered. I consider this information
useful for client developers, and will therefor keep this constructor.
`AuthSaslFailure' wraps a `SaslFailure' (from Types.hs) and is only
thrown when `pullSaslElement' unpickles a SASL failure. This, together
with `AuthNoAcceptableMechanism' above, could be considered the
`normal' ways of which SASL might be failing.
`AuthStringPrepFailure' is thrown if `prepCredentials' fails to
stringprep-verify the credentials. This might be interesting for the
client developer. As I think that `AuthIllegalCredentials' is more
understandable, I have changed the name to that.
`AuthNoStream' is thrown by `xmppSasl' when the stream state is
`Closed'. This is the result of a client program error/bug. This patch
removes this constructor and modifies the behaviour of xmppSasl to
throw an `XmppFailure' instead.
`AuthChallengeFailure' is thrown if `fromPairs' fails (in Scram.hs),
if a challenge element could not be pulled (in Common.hs), by
`saslFromJust' if a `Nothing' value is encountered (in Common.hs), in
`pullFinalMessage' (`decode') if the success payload could not be
decoded (in Common.hs), or if `toPairs' (in Common.hs) can not extract
the pairs. Furthermore, `AuthServerAuthFailure' is thrown if there is
no `v' value in the final message of the SCRAM handler. Finally,
`AuthXmlFailure' is thrown when `pullSuccess' find something other
than a success element (and, I'm guessing, a `SaslFailure' element).
This can only happen if there is a bug in Pontarius XMPP or the
server. The way I see it, all these failures are abnormal and are of
no interest from the client application itself. I suggest that these
events are logged instead, and that we signal any of these conditions
with a new `AuthOtherFailure' constructor.
I suggest that we remove the `AuthFailure' constructor, and use the
`AuthOtherFailure' for the `Error' instance.
The `AuthFailure' type and all its constructors are now documented.
I also made some minor documentation enhancements to the `XmppFailure'
type.
Jon Kristensen
655aeb5b6b