Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add empty tag-only message support and an increased size limit for tags #287

Merged
merged 25 commits into from Feb 16, 2017
Merged

Add empty tag-only message support and an increased size limit for tags #287

Changes from 13 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
35b2f58
Add empty tag-only message support and an increased size limit for tags
jwheare Dec 20, 2016
ac7a048
Fix typo
jwheare Dec 20, 2016
c7cb43b
Add requirement for clients to ignore empty tagged messages unless th…
jwheare Dec 20, 2016
49ead80
Add empty tagged message examples
jwheare Dec 20, 2016
e51b828
Fix shouting
jwheare Dec 21, 2016
3a249a7
Only specify the omitted message parameter form for tag-only messages
jwheare Jan 2, 2017
19f545e
Size limit typo/clarification
jwheare Jan 2, 2017
ab41d48
Bump version
jwheare Jan 2, 2017
8667e48
Clarify tags that might specify empty message displays
jwheare Jan 7, 2017
304a03c
Empty last parameter instead of omitted
jwheare Jan 10, 2017
9348000
TAGMSG instead of empty PRIVMG
jwheare Jan 13, 2017
0520f1f
[message-tags] Link to RFC1459 PRIVMSG
jwheare Jan 19, 2017
a597221
[message-tags] Add STATUSMSG and echo-message exmaples
jwheare Jan 19, 2017
c62ef7b
Better wording around rejecting tagless TAGMSG
jwheare Jan 25, 2017
4ad87c4
Add label behaviour to echo/msgid example
jwheare Jan 25, 2017
cb8218e
Add ERR_NEEDMOREPARAMS example
jwheare Jan 25, 2017
3d5d79a
Use indents for examples to improve web rendering
jwheare Jan 26, 2017
cfe3148
Potentially fix rendering of code block after list?
jwheare Jan 26, 2017
c53446d
Add a line between the list and code block to fix rendering bug
jwheare Jan 26, 2017
8cc4119
Rewording. Follow naming and command definition conventions from the …
jwheare Jan 28, 2017
5b92bd3
Link to RC2812 for PRIVMSG example as it better defines the <msgtarge…
jwheare Jan 28, 2017
b6b3f6f
Add a required error numeric for messages that exceed the size limit.…
jwheare Jan 28, 2017
3e68130
command vs message
jwheare Jan 28, 2017
96a17bc
Split the byte limit between server and client initiated tags
jwheare Feb 11, 2017
dba7cd5
Better description of split tag limits
jwheare Feb 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
86 changes: 76 additions & 10 deletions core/message-tags-3.3.md
View file
Open in desktop
Expand Up @@ -19,33 +19,41 @@ This is a work-in-progress specification.

Software implementing this work-in-progress specification MUST NOT use the
unprefixed `message-tags` capability name. Instead, implementations SHOULD use
the `draft/message-tags` capability name to be interoperable with other software
the `draft/message-tags-0.2` capability name to be interoperable with other software
implementing a compatible work-in-progress version.

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

## Introduction

This specification adds a new capability for general message tags support and
a prefix for expressing client-only tags.
a prefix for expressing client-only tags. It also defines a new event for
tag-only messages, and increases the byte limit for tags.

## Motivation

Previously, clients were required to negotiate a capability with servers for each
supported tag. This made tags inappropriate for client-only features. By adding a
new base capability, this specification allows clients to indicate support for
receiving any well-formed tag, whether or not it is recognised or used. This also
frees servers from having to filter messages tags for each individual client
frees servers from having to filter message tags for each individual client
response.

The client-only tag prefix allows servers to safely relay untrusted client tags,
keeping them distinct from server-initiated tags that carry verified meaning.

To allow for tagged data to be sent to channels and users without any accompanying
message text, a new event for tag-only messages is needed.

With the scope of tags expanded for use as general purpose message metadata, the
number and size of tags attached to a message will potentially increase. As a
result, an increased limit is implied by negotiating the new capability.

## Architecture

### Capabilities

This specification adds the `draft/message-tags` capability. Clients requesting
This specification adds the `draft/message-tags-0.2` capability. Clients requesting
this capability indicate that they are capable of parsing all well-formed tags,
even if they don't handle them specifically.

Expand Down Expand Up @@ -80,6 +88,39 @@ Individual tag keys MUST only be used a maximum of once per message. Clients
receiving messages with more than one occurrence of a tag key SHOULD discard all
but the final occurrence.

### The `TAGMSG` tag-only event

A new event `TAGMSG` is defined for sending messages with tags but no text content.
This event MUST be delivered to targets in the same way as `PRIVMSG` and `NOTICE`
events. This means for example, honouring channel membership, modes,
[`echo-message`](../extensions/echo-message-3.2.html),
[`STATUSMSG`](https://tools.ietf.org/html/draft-hardy-irc-isupport-00#section-4.18)
prefixes, etc.

Servers MAY apply moderation to this event using existing or newly specified modes or
configuration.

These events MUST NOT be delivered to clients that haven't negotiated the message tags
capability and MAY be rejected if no tags are included.

If this event is sent without any tags, servers SHOULD reject it with a standard
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not that important, but any reason this is not a MUST? i.e. if servers choose to disallow tagless TAGMSG then they must use the given numeric for that. As currently stands servers are allowed to do whatever they want with a tagless TAGMSG making this a useless requirement.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a SHOULD in case servers don't want to bother to check the tags on TAGMSG for simplicity, since clients receiving them would be a no-op anyway.

How about this:

If this event is sent without any tags, servers SHOULD reject it. If they do, the standard ERR_NEEDMOREPARAMS error numeric MUST be used.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually no, I hadn't re-read the previous paragraph, I'll find a better wording.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this is what I had in mind.

`ERR_NEEDMOREPARAMS` error numeric.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please expand the examples to demonstrate the correct server behavior or behaviors in this corner case.


See [`PRIVMSG` in RFC1459](https://tools.ietf.org/html/rfc1459#section-4.4.1) for more details on replies and examples.

Clients that receive the `TAGMSG` event MUST NOT display them in the message history
except according to the specifications of the attached tags.

The pseudo-BNF for this event is as follows:

<message> ::= '@' <tags> <SPACE> [':' <prefix> <SPACE> ] 'TAGMSG' <SPACE> <target> <crlf>

### Size limit

The size limit for message tags is increased from 512 to 4096 bytes, including the leading
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm afraid that this creates an incentive for third parties to create custom extensions which move text of message to @example.com/text, to workaround the limit of 512

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be in direct contravention of the recommendation in the spec.

There is no guarantee that other clients will support or display the client-only tags they receive, so these tags should only be used to enhance messages with non-critical information. Messages should still make sense to clients with no support for tags.

If clients do that with their own prefixed tags, then they should expect it not to be widely adopted. I don't see it as a very effective incentive.

`@` and trailing space characters, leaving 4094 bytes for tags themselves. The size limit
for the rest of the message is unchanged.

## Security considerations

Client-only tags should be treated as untrusted data. They can contain any value
Expand Down Expand Up @@ -111,15 +152,15 @@ This section is non-normative. The tags used in these examples may or may not ha
A message sent by a client with the `example-tag` tag:

```
@example-tag=example-value PRIVMSG #channel :Message
C: @example-tag=example-value PRIVMSG #channel :Message
```

---

A message sent by a client with the `+example-client-tag` client-only tag:

```
@+example-client-tag=example-value PRIVMSG #channel :Message
C: @+example-client-tag=example-value PRIVMSG #channel :Message
```

---
Expand All @@ -130,16 +171,16 @@ Server responses for:
* The bot `url_bot` responding with the URL title in the message body and the favicon URL included as the value of the `+icon` client-only tag:

```
:nick!user@example.com PRIVMSG #channel :https://example.com/a-news-story
@+icon=https://example.com/favicon.png :url_bot!bot@example.com PRIVMSG #channel :Example.com: A News Story
S: :nick!user@example.com PRIVMSG #channel :https://example.com/a-news-story
S: @+icon=https://example.com/favicon.png :url_bot!bot@example.com PRIVMSG #channel :Example.com: A News Story
```

---

An example of a vendor-prefixed client-only tag:

```
@+example.com/foo=bar :irc.example.com NOTICE #channel :A vendor-prefixed client-only tagged message
C: @+example.com/foo=bar :irc.example.com NOTICE #channel :A vendor-prefixed client-only tagged message
```

---
Expand All @@ -152,5 +193,30 @@ A client-only tag `+example` with a value containing valid raw and escaped chara
In this example, plus signs, colons, equals signs and commas are transmitted raw in tag values; while semicolons, spaces and backslashes are escaped. [Escaping rules](./message-tags-3.2.html#escaping-values) are unchanged from IRCv3.2 tags.

```
@+example=raw+:=,escaped\:\s\\ :irc.example.com NOTICE #channel :Message
C: @+example=raw+:=,escaped\:\s\\ :irc.example.com NOTICE #channel :Message
```

---

A tag-only message sent by a client with the `+example-client-tag` client-only tag:

```
C: @+example-client-tag=example-value TAGMSG #channel
```

---

A tag-only message sent by a client to channel ops with a client-only tag and `STATUSMSG` prefix:

```
C: @+example-client-tag=example-value TAGMSG @#channel
```

---

A tag-only message sent with a client-only tag and returned by the server as an `echo-message` with `msgid` tag:

```
C: @+example-client-tag=example-value TAGMSG @#channel
S: @msgid=123abc;+example-client-tag=example-value :nick!user@example.com TAGMSG @#channel
```