~samwhited/xmpp

52551ca97e766e3c65c9780a0eabbc2f0446ebf6 — Sam Whited 1 year, 9 months ago d0e7cad
design: answer a question in iqmux proposal

Update the IQ mux proposal to make it clear that Error and Result type
IQs are also handled by the multiplexer, and add some shortcut functions
for handling them in a reasonable way.
1 files changed, 35 insertions(+), 9 deletions(-)

M design/0002_iqmux.md
M design/0002_iqmux.md => design/0002_iqmux.md +35 -9
@@ 32,7 32,7 @@ meant for matching IQ payloads.

## Proposal

The proposed API creates three new types and five new functions that would need
The proposed API creates three new types and seven new functions that would need
to remain backwards compatible after we reach 1.0.

    type IQHandler interface {


@@ 53,6 53,19 @@ to remain backwards compatible after we reach 1.0.
    }
        IQMux is an XMPP multiplexer meant for handling IQ payloads.

        IQs are matched by the type and the XML name of their first child element
        (if any). If either the namespace or the localname is left off, any
        namespace or localname will be matched. Full XML names take precedence,
        followed by wildcard localnames, followed by wildcard namespaces.

        Unlike get and set type IQs, result IQs may have no child element, and error
        IQs may have more than one child element. Because of this it is normally
        adviseable to register handlers for type Error without any filter on the
        child element since we cannot guarantee what child token will come first and
        be matched against. Similarly, for IQs of type result, it is important to
        note that the start element passed to the handler may be nil, meaning that
        there is no child element.

    func NewIQMux(opt ...IQOption) *IQMux
        NewIQMux allocates and returns a new IQMux.



@@ 68,28 81,41 @@ to remain backwards compatible after we reach 1.0.
    type IQOption func(m *IQMux)
        IQOption configures an IQMux.

    func ErrorIQ(h IQHandler) IQOption
        ErrorIQ is a shortcut for HandleIQ with the type set to "error" and a
        wildcard XML name.

        This differs from the other IQ types because error IQs may contain one or
        more child elements and we cannot guarantee the order of child elements and
        therefore won't know which element to match on. Instead it is normally wise
        to register a handler for all error type IQs and then skip or handle
        unnecessary payloads until we find the error itself.

    func GetIQ(n xml.Name, h IQHandler) IQOption
        GetIQ is a shortcut for HandleIQ with the type set to "get".

        For more information, see HandleIQ.

    func HandleIQ(iqType stanza.IQType, n xml.Name, h IQHandler) IQOption
        HandleIQ returns an option that matches the IQ payload by XML name and IQ
        type.
        type. For readability, users may want to use the GetIQ, SetIQ, ErrorIQ, and
        ResultIQ shortcuts instead.

        For more details, see the documentation on IQMux.

    func HandleIQFunc(iqType stanza.IQType, n xml.Name, h IQHandlerFunc) IQOption
        HandleIQFunc returns an option that matches the IQ payload by XML name and
        IQ type.

    func ResultIQ(n xml.Name, h IQHandler) IQOption
        ResultIQ is a shortcut for HandleIQ with the type set to "result".

        Unlike IQs of type get, set, and error, result type IQs may or may not
        contain a payload. Because of this it is important to check whether the
        start element is nil in handlers meant to handle result type IQs.

    func SetIQ(n xml.Name, h IQHandler) IQOption
        SetIQ is a shortcut for HandleIQ with the type set to "set".

        For more information, see HandleIQ.

## Open Questions

 - What should we do if an `IQMux` is registered on a top level element other
   than IQ?
 - If an error or result type IQ response is sent after an IQ times out and is
   no longer handled by the server, should the IQ mux handle those too (and what
   should the behavior be)?