Proposal for RFC 3
dvdrw
Last attempt had bad formatting, somehow. In either case,
open the attached copy
and view with a monospace (equal-width) font.
Request for Comments:
3 dvdrw
Proposal
SenatorHitla
Chat Messages
Status of This Memo
This document describes the form, function, and
specifies the technical
details of a compliant chat implementation.
Abstract
Chat is, perhaps, the central feature of
[bitwave.tv]. It is the counterpart
to the stream. It is implemented using a custom
protocol that has been,
historically, subject to change.
Chat provides a mechanism for direct feedback from
authenticated users to a
streamer; or as means of communication between chat
users themselves.
Assuming equal post rates for all users, chat is
primarily a consumption
service -- spending most of its 'time' delivering
messages to a user rather
than receiving messages from that user.
Chat is also relatively time-sensitive: exact chat
message ordering isn't
necessary, though (near) real-time transmission of
messages is.
Chat is also primarily targeted to be used via web
interfaces, limiting the
effective choice of transport protocols and formats.
Table of Contents
1. Definitions
2. Chat Users
2.1 Authentication
2.2 User Data
2.3 Channels and Channel Owners
2.4 Global/Local Visibility
2.5 User Badges
3. Chat Messages
3.1 Incoming Messages
3.1.a Format of Incoming Messages
3.2 Chat Message Visibility
3.3 Chat Message Integrity
3.3.a Emotes
3.4 Client Commands
3.5 Client Rendering
4. Transport and Protocol
1. Definitions
CHAT USER is an authenticated user with authorization
to post chat messages.
CHAT MESSAGE is the unit of user post. It is
associated with a CHAT ROOM.
CHAT ROOM is a named group of users that contains
CHAT MESSAGES.
CHAT CLIENT is the tool users use to access this
service.
CHAT SERVER is the server that provides this service.
2. Chat Users
2.1 Authentication
Since chat is a subservice to the [bitwave.tv]
website, it is thereby
subordinate to its authentication service(s).
Authentication to chat is done via session tokens
that can be requested
using [bitwave.tv] API. Only one token can be
valid per user
simultaneously.
Users that are successfully authenticated to chat
are considered
connected.
Multiple connections using the same token are
allowed.
2.2 User Data
Users have associated with them a username,
avatar, username color and
user tag.
Avatars are passed as URLs to a subdomain of
'bitwave.tv.'.
Username colors are passed in hex code format
compatible with CSS3.
User tags are displayed immediately preceding a
user's username.
Connected users also have a current channel.
2.3 Channels and Channel Owners
Messages from users are sent to channels.
Channels are distinguished
by their name, case-insensitively.
Users whose username is case-insensitively equal
to a channel name are
that channel's owner.
Since usernames are unique, and channel name is
the distinguishing
factor for channels, the mapping from user to the
channel they own is a
bijection.
In other words, the mapping from user to the
channel they own MUST
be bijective.
Arbitrary channels are allowed.
2.4 Global/Local Visibility
Compliant chat clients SHOULD keep track of a
global/local visibility
flag.
This flag represents the user's ability to view
messages sent to
channels other than the one they are in.
With global visibility, they are able to see all
chat messages.
With local visibility, they only see chat
messages sent in their current
channel.
Compliant chat clients SHOULD include the current
state of this flag in
each message they send (see section 3)
2.5 User Badges
A user badge is a string that is displayed
immediately preceding the
user's username.
Rich content MUST be delivered by self-contained
HTML.
3. Chat Messages
Connected users can send chat messages. They are sent
as JSON objects to the
chat server, and have the following fields:
- message: string ; The content of the
message
- channel: string ; The name of the
channel to which the message is
being sent to
- global: boolean ; The flag representing
the user's current
global/local visibility (see:
2.4 and 3.2)
- showBadge: boolean ; Whether or not to
display the user's badge
for this message
3.1 Incoming Messages
Incoming messages are delivered as JSON objects
with the following
fields, in no particular order:
- avatar: string ; URL to the avatar
of the user who sent the message
- badge: string ; User badge (see
2.5)
- userColor: string ; Username color in
CSS3-compatible hex form
- message: string ; Contents of the
message (see 3.1.a)
- timestamp: number ; Unix-epoch
timestamp in milliseconds
- username: string ; Username of the
user who sent the message
- channel: string ; The channel to
which the message was sent
- global: boolean ; (optional)
Global/Local visibility tag (see 2.4)
- type: string ; Reserved
- id: string ; This message's UUID.
Entirely unique.
3.1.a Format of Incoming Messages
Incoming messages are formatted using
self-contained HTML and CSS.
Incoming messages MUSTN'T contain executable code
embedded in the HTML.
Messages may contain <img> tags whose 'src'
attribute MUST be set to a
valid URL with a host that is a subdomain to
'bitwave.tv.'.
3.2 Chat Message Visibility
Compliant clients may choose to (not) display
messages arbitrarily to
the end user.
Compliant chat clients SHOULD provide a mechanism
for maintaining a list
of users whose messages are automatically not
displayed, called an
'ignore list'.
Compliant chat clients SHOULD respect
global/local visibility (see 2.4).
3.3 Chat Message Integrity
Sent messages may have their message contents
edited by the chat server
before being relayed to other users. This is done
to support formatting,
emotes, and prevent malicious behavior.
Compliant chat servers MUST accept, and be able
to format, a subset of
Markdown, including, but not limited to: (1)
headings (2) bold
(3) italics (4) underline (5) superscript (6)
(un)ordered lists
(7) inline code (8) code block.
Compliant chat servers MUST accept, and be able
to format, emotes.
3.3.a Emotes
Emotes are (optionally animated) images embedded
into chat message body
text.
Client-side, emotes have the form:
emote := ':' identifier ':'
identifier := validCharacter |
identifier validCharacter
validCharacter := /[A-z0-9]/
Servers MUST transform emotes into <img>
tags (see 3.1.a) for
identifiers they support. Emotes with identifiers
the server does not
recognize MUST remain unchanged.
3.4 Client Commands
Messages starting with the character '/' with
alphanumeric characters
immediately following it MUSTN'T be sent.
These messages are client commands. The exact
behavior and existence of
each is implementation defined [1], except for
the command: '/whisper'.
3.5 Client Rendering
Messages SHOULD be rendered using the HTML markup
they're delivered in.
Messages that contain a substring separated by
whitespaces of the format
@username
where 'username' is the user's username SHOULD
trigger the playing of a
notification sound, and SHOULD have the matched
substring highlighted.
4. Transport and Protocol
Communication is done via socket.io sockets (see:
https://socket.io/docs/
for more info)
The hostname and URL for the server are
implementation defined [2].
4.1 Initiation and Maintaining a Connection
Upon successful connection, the server MUST issue
a 'connect' event. The
client then MUST reply with a 'new user' event
which will deliver a USER
PROFILE JSON object.
The USER PROFILE object has the following fields:
- token: string ; Session
token used for authentication
- channel: string ; The user's
current channel
- recaptcha: undefined ; Reserved
In case a drop in connection happens, the server
will issue a
'reconnect' event. Compliant clients SHOULD then
download chat messages
via REST API. The endpoint for this is
implementation defined [3].
It MUST be done via the GET method.
This is a compromise between securing delivery of
messages and server
overhead.
In case of error, the server MUST issue an
'error' event that delivers
an implementation defined [4] object.
4.2 Receiving Data
To deliver messages to the client, the server
does so in bulk to save on
network round-trips. Namely, the server MUST
deliver messages using the
'bulkmessage' event.
This event delivers an array of message objects
(see 3.1).
To maintain an updated list of connected users on
the client, the
server SHOULD be able to request the client
download the list again via
REST API.
This is conducive to minimizing unnecessary
requests for this resource,
as the server can request updates only when
updates are necessary.
The endpoint for this is implementation defined
[5]. It MUST be done via
the GET method.
4.3 Sending Messages
Messages MUST be sent from the client via the
'message' event. It sends
a message object defined in section 3.
5. References
[1-5] - More info about this can be found
under the same reference number
and/or reference to specific section in the
implementation
documentation/compliance report.
Jim
Proposal
Whispers as Private Communication Via Chat
Status of This Memo
This document specifies the expected features and optional features for
Whispers Via Chat.
Abstract
Chat needs a private way to communicate from user to user. This feature
has been a basic staple and will be described and outlined bellow.
By outlining features and describing how whispers MUST work and SHOULD work
in chat we will be able to maintain a consistent user experience.
The following sections will outline requirements for a functional whisper
system to be implemented. Covered will be the several aspects of how users
expect to interact with whispers: Sending and receiving.
Table of Contents
1. Definitions
3. Protocol
3.1 Sending via [bitwave.tv] API
3.2 Receiving whisper messages
4. Headers and message format
5. User Interface
5.1 Displaying a WHISPER
5.2 Responding
5.3 Autocompletion
5.4 Additional interfaces for WHISPER display
1. Definitions
CHAT USER as defined in 1. RFC 3 'Chat Messages'
USER INPUT is when ever a USER sends a message, via a send button or
enter key in chat.
USERNAME a unique name used to address and send a WHISPER to a specific
CHAT USER.
WHISPER is a private message intended to be sent to a CHAT USER.
SEPARATOR is used to split at string into arguments and is ' ' a single
white space.
WHISPER MESSAGE is a message to be sent to a CHAT USER, after a WHISPER
command has been parsed. It is considered everything after the RECEIVER
and SEPARATOR in the command. The message SHOULD have a well defined
character limit in the [bitwave.tv] API.
RECEIVER is a USERNAME that a WHISPER MUST be sent to.
[] is used to denote an optional character or string. Example:
[@]thing
'@' would be considered an optional character, not required, but SHOULD
be accepted for compatibility.
WHISPER COMMAND is a text input that MUST be parsed from CHAT USER input
used to send a WHISPER.
2. Command format
When working with a text based input from a CHAT USER the following command
format MUST be supported:
The client command '/whisper' (as defined in 3.4 of RFC 3)
The command '/w' SHOULD also be supported as valid shorthand for '/whisper'.
The command MUST have two arguments, the first being the [@]RECEIVER and the
second being the WHISPER MESSAGE. The arguments are separated with a SEPARATOR.
The following would be considered a valid command:
'/w{hisper,""} [@]RECEIVER WHISPER MESSAGE'
The '@' symbol is optional when sending a WHISPER.
After the USER INPUT has been parsed into the WHISPER COMMAND with a
RECEIVER and the WHISPER MESSAGE it can be sent via the protocol described
in the next section.
3. Protocol
There is one working way to send a WHISPER. After parsing a USER INPUT for
the WHISPER formatted command, a WHISPER MUST be sent via the
[bitwave.tv] API.
(1) Sending via [bitwave.tv] API
The API endpoint defined for sending a WHISPER is contained in the
[bitwave.tv] API.
It requires a JSON formatted payload with a:
chatToken, receiver, and message
Where chatToken is a session token that can be requested using
[bitwave.tv] API.
Where receiver is the name of the CHAT USER the WHISPER should
be sent to stored as a string.
Where message is the full string WHISPER MESSAGE to be sent.
Example data payload to send a WHISPER using JSON in javascript:
const data = {
chatToken:'validsessiontoken',
receiver:'usernamesendingthemessageto',
message:'this is the message to be sent',
}
This is done via a 'POST' request, it is expected that it returns
a 200 success status. Bellow is an example JSON response:
{"success":true,"message":"Whisper sent","id":"messageid"}
(2) Receiving whisper messages
When you are connected to chat, you will receive a chat WHISPER message
on the special channel 'whisper'. Whisper messages otherwise follow
standard message formatting (as defined in 3 of RFC 3) . You will also
receive a confirmation of the message being sent as well if you are
connected to active chat socket. A valid implementation MUST pass a
WHISPER to connected clients matching the RECEIVER.
4. Headers and message format
Headers for display in chat MUST be like the following:
[to: RECEIVER]
The rest of the message that was sent follows after the header.
The message format MUST be formatted using standard message processing and
prepend the message with the header shown above (which should have
additional html markup)
5. User Interface
(1) Displaying a WHISPER
The user interface MUST accommodate a way to display WHISPER messages.
When a message is received by a CHAT USER it SHOULD be added to chat
messages and shown with the rest of the messages.
(2) Responding
The user interface SHOULD provide a way to respond to WHISPER a
CHAT USER. One suggested way is to click the user icon in chat. Another
possible way is to allow the clicking of the username in the displayed
chat message. When a message has been clicked to WHISPER a user, it will
autocomplete the user input to be ready to send a WHISPER MESSAGE to
that user.
(3) Autocompletion
The user interface SHOULD also provide a autocomplete method to help
detect a WHISPER COMMAND and suggest users that can be sent to and help
complete the command formatting up until the WHISPER MESSAGE.
(4) Additional interfaces for WHISPER display
The user interface SHOULD also provide a way to show the most recently
received WHISPER messages, this is done as a convenience for fast moving
chat and is optional.
6. References
Consult additional RFC's on Chat Messages and the [bitwave.tv] API.
dvdrw
Vote to APPROVE for both proposals.
--
You received this message because you are subscribed to the Google Groups "RFC Committee" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rfccommittee...@bitwave.tv.
To view this discussion on the web visit https://groups.google.com/a/bitwave.tv/d/msgid/rfccommittee/4026b25c-ff27-fcb9-6f55-1583f336d834%40gmail.com.
Jim
Vote to APPROVE for both proposals.
To view this discussion on the web visit https://groups.google.com/a/bitwave.tv/d/msgid/rfccommittee/a1f89339-8b77-9df1-d305-9e7cc8472a4a%40bitwave.tv.
