Labeled responses

Notes for implementing work-in-progress version

This is a work-in-progress specification.

Software implementing this work-in-progress specification MUST NOT use the unprefixed label tag or labeled-response CAP/batch names. Instead, implementations SHOULD use the draft/label tag, draft/labeled-response-0.2 CAP and draft/labeled-response batch names to be interoperable with other software implementing a compatible work-in-progress version.

The final version of the specification will use an unprefixed tag name.

Introduction

This specification adds a new message tag sent by clients and repeated by servers to correlate responses with a specific request.

Motivation

Certain client actions can result in responses from the server that vary in interpretation depending on how they were triggered, or otherwise lack a robust way to correlate with local state. Clients have historically needed to keep track of additional local state and/or apply comparison heuristics to server responses to correlate these appropriately.

Labeled responses enable a much simpler form of correlation by using a single id attached to a client request and repeated by the server in its response.

Additionally, labeled responses allow bouncers with multiple connected clients to direct responses (such as WHOIS queries or error messages, see examples) to the correct recipient.

Architecture

Dependencies

This specification uses the message tags framework and the batch capability which SHOULD be negotiated at the same time.

Capabilities

This specification adds the draft/labeled-response-0.2 capability.

Clients requesting this capability indicate that they are capable of handling the message tag described below from servers.

Servers advertising this capability indicate that they are capable of handling the message tag described below from clients, and will use the same tag and value in their response.

Batch types

This specification adds the draft/labeled-response batch type, described below.

Tags

This specification adds the draft/label message tag, which has a required value.

This tag MAY be sent by a client for any messages that need to be correlated with a response from the server.

For any message received from a client that includes this tag, the server MUST include the same tag and value in any response required from this message where it is feasible to do so. Servers MUST include the tag in exactly one logical message.

If a response consists of more than one message, and the batch capability is enabled, a batch MUST be used to group them into a single logical response. The start of the batch MUST be tagged with the draft/label tag. The batch type MUST be one of:

• An existing type applicable to the entire response
• draft/labeled-response

If batch has not been enabled, the tag MAY be included on only one of the messages in the response.

When a client sends a message to itself, the server MUST NOT include the label tag, except for any acknowledgment sent with the echo-message mechanism. This allows clients to differentiate between the echoed message response, and the delivered message.

Tag value

The tag value is chosen by the client and MUST be treated as an opaque identifier. The client SHOULD NOT reuse a tag value until it has received a complete response for that value from the server. The value MUST NOT exceed 64 bytes.

The ACK response

Servers MUST respond with a labeled ACK message when a client sends a labeled command that normally produces no response. It takes no additional parameters and is defined as follows

:irc.example.com ACK

Client implementation considerations

This section is non-normative.

Bear in mind that in some cases, it might not be feasible for servers to attach a label to a message, for instance on certain remote or asynchronous actions. Handle these cases as normal for a server with no support for labeled responses.

In the case of echo-message (see example below), a client can use labeled responses to correlate a server’s acknowledgment of their own messages with a temporary message displayed locally. The temporary message can be displayed to the user immediately in a pending state to reduce perceived lag, and then removed once a labeled response from the server is received.

When a client sends a private message to its own nick, echo-message will result in duplicate messages being sent by the server, as both sent and received messages. Labeled responses allow clients to deduplicate these messages in one of two ways:

1. Ignore the labeled message, and use any unlabeled message as acknowledgment for all sent messages to clear temporary local messages.
2. Ignore the unlabeled message.

Both methods assume that the server will acknowledge all successful messages, or return a labeled error response, but differ in their attitude towards the semantics of sending and receiving.

Bouncer implementation considerations

This section is non-normative.

Bouncers might choose to restrict routing labeled responses to some or all of their clients. For example, the response to a labeled WHOIS request might only be routed back to the originating client. However, an echo-message response might be routed to all clients. The bouncer might also choose to make labeled requests to the server on its own behalf, without routing any response to clients.

To avoid label value clashes from multiple connected clients, a bouncer could choose to modify the client supplied label, for instance, by adding a client id prefix. In this case, the modified label would be converted back to its original form before routing the response back to the client.

Examples

This section is non-normative.

echo-message showing a message that has been modified by the server to remove formatting

Client: @label=pQraCjj82e PRIVMSG #channel :\x02Hello!\x02
Server: @label=pQraCjj82e :nick!user@host PRIVMSG #channel :Hello!

Failed PRIVMSG with ERR_NOSUCHNICK

Client: @label=dc11f13f11 PRIVMSG nick :Hello
Server: @label=dc11f13f11 :irc.example.com 401 * nick :No such nick/channel

WHOIS response using a batch

Client: @label=mGhe5V7RTV WHOIS nick
Server: @label=mGhe5V7RTV :irc.example.com BATCH +NMzYSq45x labeled-response
Server: @batch=NMzYSq45x :irc.example.com 311 client nick ~ident host * :Name
...
Server: @batch=NMzYSq45x :irc.example.com 318 client nick :End of /WHOIS list.
Server: :irc.example.com BATCH -NMzYSq45x

A server replying with ACK where no response is required

Server: PING :foobar
Client: @label=abc PONG :foobar
Server: @label=abc :irc.example.com ACK

Alternatives

For the use case of bouncers directing query responses to the appropriate client, there exists prior art in the form of the znc module route_replies. The complexities and limitations of that module were a primary motivation for the standardised approach described in this specification.

Software supporting draft/labeled-response: IRCCloud Teams, Oragono, IRCCloud, Palaver, IRCCloud (as Server), BitBot