XEP-0317: Hats, Update and complete the protocol

[edhelas]

As a client developper the current Hats XEP is far from be usable and feature complete.

The goal of those changes is to:

• Allow clients to develop a nice UI to manage and assign hats, for example like Discord is doing (see https://support.discord.com/hc/en-us/articles/214836687-Discord-Roles-and-Permissions)
• Reconciliate existing implementations and their specificities, see https://docs.ejabberd.im/tutorials/muc-hats/
• Those changes were meant to be backward compatible with the current 0.2.0 version

This PR make the following changes:

• Specify a urn:xmpp:hats:commands:dcreate command to add a hat to the available list
• Specify a urn:xmpp:hats:commands:ddestroy command to destroy a hat from the list
• Clarify how the service should broadcast the hat changes when it is edited, assigned, removed or destroyed
• Specify a way for an entity to get the complete list of hats using a hash in disco#info
• Add a hue optional parameter allowing entities to assign a color to the hat that can be displayed properly in any conditions on the client (as explained in XEP-0392: Consistent Color Generation)
• Standardize the all the form fields using XEP-0068
• Rename the :dlist, :don and :doff commands to :list, :assign and :unassign
• Add myself in the list of authors
• Fix some typos

The HTML generated version of this PR is available here: https://movim.eu/xeps/xep-0317.html

[lovetox]

If we need a notification mechanism, we can use the MUC Status that the config changed. See https://xmpp.org/extensions/xep-0486.html#example-7 for an example.

It does not really matter if the config is really available via MUC Config form.

What client usually do after receiving the status code, is disco the room.

So i would propose to put the full configured list of hats into disco info. That gives us out of the box a way to query the data and receive a notification when something changes. And its in line with other muc configuration which is also available in disco info.

[edhelas]

@lovetox what kind of syntax would you use to list the hats in the disco#info ? 🤔

[lovetox]

hm i thought we could include a <reported> form, but seems those have no FORM_TYPE value, and therefore we cannot discover that this form belongs to hats.

Seems we are only allowed to add normal forms to disco, and these tabular data would be quite ugly in a form.

the only other idea i would have is that the room provides a hats hash in disco info. (analog to the avatar hash)
How this hash is generated is up to the server.

whenever this hash changes we know we need to query the hats via adhoc form. Basically doing exactly what we do with avatar hash, just that we dont query vcard and instead executing an adhoc command get-hats or whatever.

[edhelas]

A hash could work and prevent those disco#info to be very verbose (I anticipate some MUCs to have like 100 hats configured like on some Discord servers).

But I'm still figuring out how you can list all the hats in a form while also integrating all their attributes, basically URI, Title and Hue Color at the moment 🤔

[lovetox]

Ah now i understand because adhoc is also a dataform..

[edhelas]

@lovetox I've updated my PR with a hash + dlist query that returns a form

[edhelas]

I added Field Standardization using XEP-0068

[stpeter]

With my author hat on (!), this looks good to me. See feedback on the list as well.

[edhelas]

@mwild1 It seems that you had a few feedback to give on the XEP, feel free to do so then I can amend it (or amend it yourself with a PR :) ).

[mwild1]

I've left suggestions inline, fixing some minor nits. There are two other changes I would like to request:

• Make it clear that the "hat list" and all associated commands are optional. Clients may receive hats from the server, even if these commands are not exposed. As mentioned on the mailing list, many deployments will pull hat information from external sources, such as LDAP and may not want to offer control over these.
• Replace uses of 'don' and 'doff' with 'assign' and 'unassign' for clarity (the word "don" typically applies to dressing oneself, and originally the commands were specified this way, but now the commands are about admins giving hats to other people - combined with the general unfamiliarity of these words I think it is best if we change them while we still can).

[edhelas]

@mwild1 @stpeter I took care of all your feedbacks, and added myself in the authors list if you don't mind :)

I recompiled the XEP there https://movim.eu/xeps/xep-0317.html