Okay: Difference between revisions
No edit summary |
No edit summary |
||
Line 43: | Line 43: | ||
margin-left: auto !important; | margin-left: auto !important; | ||
margin-right: auto !important; | margin-right: auto !important; | ||
margin-top: 0; | |||
} | } | ||
}}<p class="lede">'''Okay''' dares to ask the big questions. What if group chat was hypertext? What if discord let you write arbitrary HTML? What if protocols were bad?</p> | }}<p class="lede">'''Okay''' dares to ask the big questions. What if group chat was hypertext? What if discord let you write arbitrary HTML? What if protocols were bad?</p> |
Revision as of 01:42, 26 February 2025
Okay dares to ask the big questions. What if group chat was hypertext? What if discord let you write arbitrary HTML? What if protocols were bad?
in summary
Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from a “Space”.
- A room is just a special URI which you can POST messages to and GET them back from at a later date.
- You can use WebSockets to get a real-time feed of events that you’re interested in.
- Events are represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. This also lets you do really really stupid things with your messages.
- Every client is authenticated with a certificate that gets generated by the client on first use.
conventions
The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may”, and “optional” in this document are to be interpreted as described in BCP14, although we use bold colourful text instead of capitals (so it doesn't look like we're yelling at you. this is a relaxed and cordial protocol specification).
controversies
what “server” means is kind of nebulous.- what do we do about invalid html
connection flow
A typical connection to an never before seen space usually goes like this:
- The user hands the client a URI to examine;
- The client issues a GET request to the URI and examines the response;
- If the response meets all the discovery requirements, it generates a new certificate and registers itself with the spaces’s registration endpoint;
- Once everyone’s happy, the client can begin posting messages to rooms.
spaces
A space is a container for rooms and accounts. In practical terms, a space is a HTML document that contains links to resources associated with the space; this document is known as the space's root. Each space root must meet all discovery requirements and must provide some metadata for clients to display, a room directory, and preferences page.
discovery
For a client to recognise a URI as a space, it must:
- Respond with 200 OK upon a GET request;
- Have a Content-Type of text/html;
- Respond with a valid HTML document, -- TODO: define valid;
- Have the Access-Control-Allow-Origin header set to
*
; - Contain a valid discovery element.
If multiple discovery elements are present on a page, the client should ask the user to select which space it should use.
the element thereof
The discovery element provides a list of resources associated with the space. They look like this:
<nav class=“ok-discover”>
<a href=“/rooms/” rel=“ok-rooms”>Rooms</a>
<a href=“/register/” rel=“ok-register”>Registration</a>
<a href=“/prefs/” rel=“ok-prefs”>Preferences</a>
</nav>
The discovery element is defined as any element with the ok-discover
class. Any non-void element can be the discovery element, but it really should be a <nav />
if you can help it. The discovery element must contain a number of anchor (<a />
) elements with valid rel
and href
attributes. Any invalid anchors must be ignored by the client. The inner text of the anchor elements is not significant and must be ignored by clients.
A list of valid anchor rel
attributes and their purposes is described below:
Key: ◈ Required, ◇ Optional, ❖ Can be specified multiple times
◈ | ok-rooms
|
The space's room directory. |
◈ | ok-register
|
The space's registration page. |
◈ | ok-prefs
|
The space's preferences page. |
initiation
A client must register itself with a space before it can send messages to rooms.
the directory
The Room Directory is a list of every room contained within the space. This list may be paginated.
The path to the space's room directory must be defined in its discovery element with the ok-rooms
rel value.
Here's an example of what a room directory might look like:
<main class="ok-rooms">
<h1>Rooms on This Server</h1>
<ul>
<li><a href="/rooms/1" class="ok-room">General</a></li>
<li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>
</ul>
</main>
sections
Clients may recognise a <section />
element containing a heading element of any level and any number of room links to be a "section" and present it as such in the user interface.
rooms
messages
profiles
subscriptions
settings
pagination
critical reception
It’s okay.