diff --git a/extensions/extended-isupport.md b/extensions/extended-isupport.md index 7936e1db..116035ed 100644 --- a/extensions/extended-isupport.md +++ b/extensions/extended-isupport.md @@ -7,6 +7,10 @@ copyrights: name: "Simon Ser" period: "2024" email: "contact@emersion.fr" + - + name: "Valerie Pond" + period: "2026" + email: "v.a.pond@outlook.com" --- ## Notes for implementing work-in-progress version @@ -14,10 +18,11 @@ copyrights: This is a work-in-progress specification. Software implementing this work-in-progress specification MUST NOT use the -unprefixed `extended-isupport` capability name. Instead, implementations SHOULD -use the `draft/extended-isupport` capability name to be interoperable with -other software implementing a compatible work-in-progress version. The final -version of the specification will use unprefixed capability names. +unprefixed `extended-isupport` capability name or `isupport` batch name. +Instead, implementations SHOULD use the `draft/extended-isupport-0.2` +capability name and the `draft/isupport` batch name to be interoperable +with other software implementing a compatible work-in-progress version. +The final version of the specification will use unprefixed names. ## Introduction @@ -29,6 +34,12 @@ extension adds a mechanism to send `RPL_ISUPPORT` messages before connection registration, as well as a dedicated command to request the `ISUPPORT` list and a batch for `RPL_ISUPPORT` messages. +Additionally, the standard `RPL_ISUPPORT` semantics treat a repeated token as +a replacement, not an extension, which combined with the 512-byte line limit +bounds the size of any single token's value at roughly 400 bytes. This +extension defines an opt-in append form (`KEY+=value`) for list-valued tokens +that allows a server to deliver a value across multiple lines. + ## Implementation ### `ISUPPORT` command @@ -36,16 +47,16 @@ a batch for `RPL_ISUPPORT` messages. A new `ISUPPORT` command is introduced to request the full `RPL_ISUPPORT` list. When receiving this command, the server MUST reply with one or more `RPL_ISUPPORT` messages (grouped inside a `draft/isupport` batch if the `batch` -and `draft/extended-isupport` capabilities are enabled, see below). +and `draft/extended-isupport-0.2` capabilities are enabled, see below). -### `draft/extended-isupport` capability +### `draft/extended-isupport-0.2` capability -When the `draft/extended-isupport` capability is enabled by the client, the +When the `draft/extended-isupport-0.2` capability is enabled by the client, the server MUST accept `ISUPPORT` commands before connection registration completes (ie, before the client sends `CAP END`, and before the server sends `RPL_WELCOME`). -Before connection registration completes, while `draft/extended-isupport` is +Before connection registration completes, while `draft/extended-isupport-0.2` is enabled, the server MAY send updates to the key-value entries via subsequent `RPL_ISUPPORT` messages (the same way it would after connection registration completes without this extension). @@ -60,7 +71,7 @@ when connection registration completes with entries previously omitted. ### `draft/isupport` batch The server MUST group all `RPL_ISUPPORT` messages inside a `draft/isupport` -batch when the [`batch`][batch] and `draft/extended-isupport` capabilities are +batch when the [`batch`][batch] and `draft/extended-isupport-0.2` capabilities are enabled. The server MUST NOT send any unbatched `RPL_ISUPPORT` message while both of these capabilities are enabled. The order in which the capabilities are enabled is not significant. @@ -71,14 +82,72 @@ contain any other message. As usual, servers can update or delete existing values by sending additional `RPL_ISUPPORT` messages in a `draft/isupport` batch after the initial batch. +### Append syntax for list-valued tokens + +When the `draft/extended-isupport-0.2` capability is enabled, the syntax of an +`RPL_ISUPPORT` token is extended to: + + token = ( key "+=" value ) ; append form + / ( key "=" value ) ; replacement form + / ( key ) ; flag form + / ( "-" key ) ; deletion form + +The append form is defined as byte-wise concatenation. The client +performs no interpretation of either the current value or the appended +chunk; it simply appends the bytes of `value` to whatever bytes are +currently held for `key`. Any structural delimiter required by the +token's grammar (such as a separating comma) MUST be included by the +server inside the appended `value`. To extend a non-empty +comma-separated list, for example, the server sends the appended chunk +with a leading comma: + + KEY=foo,bar,baz + KEY+=,qux,quux,corge + +producing the final value `foo,bar,baz,qux,quux,corge`. + +The `+=` form has meaning only for `RPL_ISUPPORT` tokens whose value +grammar is explicitly defined to permit it. A token specification that +wishes to permit `+=` MUST state so explicitly, and MAY constrain +behaviour beyond byte-wise concatenation (for example, the semantics of +appending an element that is already present, or how wildcard or +exclusion markers in the token's grammar combine across appended +chunks). + +For tokens whose specification does not permit `+=`, a server MUST NOT +send the `+=` form. A client receiving `+=` for a token whose grammar is +unknown to it, or whose specification does not permit `+=`, SHOULD ignore +the append; it MUST NOT interpret it as a replacement. + +Processing rules apply token-by-token to the value the client currently +holds: + +- `KEY=value` sets the value to `value`, replacing any prior value. +- `KEY+=value` sets the value to the byte-wise concatenation of the + current value and `value`. If no value is currently held (the token has + not been advertised in this session, or was deleted), the result is + simply `value`. Whether the resulting bytes form a well-formed value + for the token is the token specification's concern, not this one's. +- `-KEY` removes the value entirely; a subsequent `KEY+=value` then + behaves as in the unset case above. +- `KEY+=` (append form with an empty value) is a no-op. + +Multiple `+=` tokens for the same key MAY appear within a single +`RPL_ISUPPORT` reply, across multiple replies, and across batches. The +order of concatenation is the order in which the tokens are received. + +A server that can fit a token's value in a single `RPL_ISUPPORT` line +SHOULD continue to use the plain `=` form. A server MUST NOT use `+=` to +clients that have not negotiated `draft/extended-isupport-0.2`. + ## Examples Enabling the capability: C: CAP LS 302 - S: :irc.example.org CAP * LS :multi-prefix sasl batch draft/extended-isupport - C: CAP REQ batch draft/extended-isupport - S: :irc.example.org CAP * ACK :batch draft/extended-isupport + S: :irc.example.org CAP * LS :multi-prefix sasl batch draft/extended-isupport-0.2 + C: CAP REQ batch draft/extended-isupport-0.2 + S: :irc.example.org CAP * ACK :batch draft/extended-isupport-0.2 C: ISUPPORT S: :irc.example.org BATCH +asdf draft/isupport S: @batch=asdf :irc.example.org 005 * NETWORK=Example NICKLEN=30 FOO=bar @@ -94,4 +163,18 @@ Sending a change: S: @batch=asdf :irc.example.org 005 * CHANNELLEN=64 NICKLEN=42 -FOO S: :irc.example.org BATCH -asdf +Delivering a list-valued token (here a hypothetical `EXAMPLELIST`) across +two lines using the append form. Note the leading comma on the appended +chunk: the server is responsible for emitting any separator required by +the token's grammar. + + S: :irc.example.org BATCH +xyz draft/isupport + S: @batch=xyz :irc.example.org 005 * EXAMPLELIST=foo,bar,baz + S: @batch=xyz :irc.example.org 005 * EXAMPLELIST+=,qux,quux,corge + S: :irc.example.org BATCH -xyz + +The resulting value held by the client is `foo,bar,baz,qux,quux,corge`. A +later plain `=` resets the accumulation; a later `-EXAMPLELIST` clears +it. + [batch]: ../extensions/batch.html