From 02f2dda8da602de8ab9ea80a7dc39e7a23458d7c Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Mon, 13 Dec 2021 18:34:12 -0500 Subject: [PATCH 1/3] strengthen labeled-response guarantee --- extensions/labeled-response.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/extensions/labeled-response.md b/extensions/labeled-response.md index e44dada3..c91bdf0e 100644 --- a/extensions/labeled-response.md +++ b/extensions/labeled-response.md @@ -50,7 +50,7 @@ This specification adds the `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. +For any message received from a client that includes this tag, the server MUST include the same tag and value in any response produced from this message, in the absence of exceptional conditions that prevent it from doing so. Servers MUST include the tag in exactly one logical message. If a response consists of more than one message, a batch MUST be used to group them into a single logical response. The start of the batch MUST be tagged with the `label` tag. The batch type MUST be one of: @@ -80,7 +80,7 @@ There are some cases where a server might not produce a labeled response, or eve * the local server has already begun responding when the netsplit occurs, so the batched response ends early. * the local server receives a response from the remote server after the netsplit resolves, and sends a `WHOIS` response to the client, potentially without any label. -Clients should handle these cases as they would normally for a server without support for labeled responses. +Typical clients should handle these cases as they would normally for a server without support for labeled responses. Other clients that require a server supporting `labeled-response` may wish to process only labeled responses, discarding unlabeled ones. In either case, clients should be resilient to failure conditions on the server side; for example, in the event that a labeled response never arrives, they should not leak resources. 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. @@ -135,3 +135,7 @@ A server replying with `ACK` where no response is required ## 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](http://wiki.znc.in/Route_replies). The complexities and limitations of that module were a primary motivation for the standardised approach described in this specification. + +## Errata + +Previous versions of the specification imposed a weaker guarantee of labeling on servers. From b145ed893abaf69e601c217cc0863115467a5552 Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Thu, 16 Dec 2021 16:28:18 -0500 Subject: [PATCH 2/3] Revert "strengthen labeled-response guarantee" This reverts commit 02f2dda8da602de8ab9ea80a7dc39e7a23458d7c. --- extensions/labeled-response.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/extensions/labeled-response.md b/extensions/labeled-response.md index c91bdf0e..e44dada3 100644 --- a/extensions/labeled-response.md +++ b/extensions/labeled-response.md @@ -50,7 +50,7 @@ This specification adds the `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 produced from this message, in the absence of exceptional conditions that prevent it from doing so. Servers MUST include the tag in exactly one logical message. +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, a batch MUST be used to group them into a single logical response. The start of the batch MUST be tagged with the `label` tag. The batch type MUST be one of: @@ -80,7 +80,7 @@ There are some cases where a server might not produce a labeled response, or eve * the local server has already begun responding when the netsplit occurs, so the batched response ends early. * the local server receives a response from the remote server after the netsplit resolves, and sends a `WHOIS` response to the client, potentially without any label. -Typical clients should handle these cases as they would normally for a server without support for labeled responses. Other clients that require a server supporting `labeled-response` may wish to process only labeled responses, discarding unlabeled ones. In either case, clients should be resilient to failure conditions on the server side; for example, in the event that a labeled response never arrives, they should not leak resources. +Clients should handle these cases as they would normally for a server without 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. @@ -135,7 +135,3 @@ A server replying with `ACK` where no response is required ## 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](http://wiki.znc.in/Route_replies). The complexities and limitations of that module were a primary motivation for the standardised approach described in this specification. - -## Errata - -Previous versions of the specification imposed a weaker guarantee of labeling on servers. From ad6dfe814d5a3ffb8cb824e6aba754fdd2554f55 Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Thu, 16 Dec 2021 18:31:35 -0500 Subject: [PATCH 3/3] make the stricter behavior an optional flag --- extensions/labeled-response.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/extensions/labeled-response.md b/extensions/labeled-response.md index e44dada3..d1e2400e 100644 --- a/extensions/labeled-response.md +++ b/extensions/labeled-response.md @@ -40,6 +40,8 @@ Clients requesting this capability indicate that they are capable of handling th 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. They will also send the batch type and `ACK` response described below where required. +The value, if present, MUST be a comma (`,`) separated list of flags. The only currently defined flag is `strict`; its semantics are given below. + ### Batch types This specification adds the `labeled-response` batch type, described below. @@ -50,9 +52,9 @@ This specification adds the `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. +For any message received from a client that includes this tag, the server MUST include the same tag and value in any response produced from this message, in cases where it is feasible to do so. Servers advertising the `strict` flag MUST include the tag and value in the absence of exceptional runtime conditions, such as a network partition or similar unrecoverable runtime error. -If a response consists of more than one message, a batch MUST be used to group them into a single logical response. The start of the batch MUST be tagged with the `label` tag. The batch type MUST be one of: +Servers MUST include the tag in at most one logical message. If a response consists of more than one message, a batch MUST be used to group them into a single logical response. The start of the batch MUST be tagged with the `label` tag. The batch type MUST be one of: * An existing type applicable to the entire response * `labeled-response` @@ -80,7 +82,9 @@ There are some cases where a server might not produce a labeled response, or eve * the local server has already begun responding when the netsplit occurs, so the batched response ends early. * the local server receives a response from the remote server after the netsplit resolves, and sends a `WHOIS` response to the client, potentially without any label. -Clients should handle these cases as they would normally for a server without support for labeled responses. +In addition to this, some server implementations may not label certain responses even under normal operating conditions; this behavior is allowed by the basic `labeled-response` capability, but is disallowed under `labeled-response=strict`. + +Typical clients should handle these cases as they would normally for a server without support for labeled responses. Other clients that require a server supporting `labeled-response` with the `strict` flag may wish to process only labeled responses, discarding unlabeled ones. In either case, clients should be resilient to failure conditions on the server side; for example, in the event that a labeled response never arrives, they should not leak resources. 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.