Add rewritten metadata specification

[attilamolnar]

TODO:

• Update numerics to match inspircd implementation
• Rewrite to include the parts of 3.2 that still apply, clarifying if necessary and mention that 3.2 is deprecated (see Deprecate metadata-3.2 for the time being. #279)
• Add a requirement that clients should expect to receive notifications even if they haven't subscribed to any key, e.g. if a server needs to update a client's own metadata, e.g. on oper, or auth, or if an oper sets a key on another user.
• Specify a cap value that advertises a limit of key and/or value names
• Drop the 3.3 versioning. (see Unbundle specifications from versioned releases #265)
• Non-normative sections in the metadata spec #278 Additional non-normative sections
• Remove RPL_METADATAEND replies, clients should use labeled-response
• Allow async processing of requests
• Change ERR_KEYINVALID to drop the message reason and include the invalid key as the last arg since it could contain spaces
• Clarify ERR_KEYNOPERMISSION to expand "not settable by the requesting user" with "or otherwise disallowed by the server"
• Allow hyphens in key names

Discuss:

• Rename CAP to just metadata (no need for version number, values are about more than notifications)

[ghost]

Depending on the order, I'd allow the client to either request both (metadata-notify and then ...-2) or allow ...-2 and reject the other.

[attilamolnar]

Any good reason to do it that way? I've deliberately tried to avoid adding special cases like "if both are present, accept only one" or "if the order is X Y accept if Y X then reject". Servers must accept all caps in a CAP REQ or reject them all per the cap spec.

[ghost]

By 'order' here I mean specifically each capability is in a REQ of its own; it doesn't make sense to reject ...-2 if metadata-notify was negotiated previously.

Clients MAY request metadata-notify-2 after a successful metadata-notify.

...may be the best way to phrase it.

[attilamolnar]

Any good reason to deliberately allow that?

[ghost]

...Well, if a client author's developing support for IRCv3.3 metadata, they might have already negotiated metadata-notify by default. It's not a particularly good reason, though, so I won't insist on it.

[ghost]

The key subscription needs to be disclosed to the client somewhere, e.g. via a METADATA key on RPL_ISUPPORT.

[attilamolnar]

The key subscription needs to be disclosed to the client somewhere, e.g. via a METADATA key on RPL_ISUPPORT.

I don't exactly understand what you mean. Can you elaborate? If this is about advertising the availability of the new subcommands, the presence of metadata-notify-2 implies support for them.

[ghost]

Sorry, I missed a word there; the key subscription limit needs to be disclosed.

[attilamolnar]

I agree, that should be advertised. I think it should be in the cap's value because we can't change the format of the value of the METADATA ISUPPORT token after release and adding a new ISUPPORT token is not necessary if there is a cap already.

[ghost]

I disagree; the METADATA token could be changed to use the same key/value format other RPL_ISUPPORT tokens use (TARGMAX, for instance), and clients should be able to figure out which version is which trivially.

[jwheare]

Changing the ISUPPORT format only if the CAP is negotiated seems reasonable.

[attilamolnar]

I disagree; the METADATA token could be changed to use the same key/value format other RPL_ISUPPORT tokens use (TARGMAX, for instance), and clients should be able to figure out which version is which trivially.

Clients released before this specification can't figure out "which version is which" because they expect a single integer as the value of the ISUPPORT token.

Changing the ISUPPORT format only if the CAP is negotiated seems reasonable.

Clients can request metadata-notify-2 after ISUPPORT (say after they receive a CAP NEW) and they won't get the value that way. Also existing servers have a cached ISUPPORT and send that to all clients. Having per client ISUPPORT is something they'd have to add support for separately for this case and it has no benefit over advertising as a cap value. (In fact, the cap value has benefits as it allows changing the limit on the fly for example).

[ghost]

Clients released before this specification can't figure out "which version is which" because they expect a single integer as the value of the ISUPPORT token.

This is a valid criticism.

Changing the ISUPPORT format only if the CAP is negotiated seems reasonable.

This is a terrible idea.

[attilamolnar]

What's the status of this? Do we need implementations for this to move forward?

[jwheare]

Yes, and I think it should be merged with #245 so we can point to a single PR from the tracker issue.

[attilamolnar]

Somewhat experimental implementation here: https://github.com/attilamolnar/inspircd/tree/master%2Bmetadata

[attilamolnar]

More ideas: Remove the End of metadata numeric sent in reply to every METADATA command, clients that want to track when the reply ends should use labeled-response. Also allow the server to asynchronously process any METADATA request (but still in order).

[jwheare]

Closing in favour of #339