Okay

From pronounmail wiki
Revision as of 12:18, 23 February 2025 by Leah (talk | contribs)
Jump to navigation Jump to search

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 fro the “Server”.

❊ 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 TLS certificate that gets generated by the client on first use.

todo list

  • what “server” means is kind of nebulous.

connection flow

A typical connection to an never before seen server 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 server’s registration endpoint;

✻ Once everyone’s happy, the client can begin posting messages to rooms.

discovery

For a client to recognise a URI as an Okay protocol server, 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 Discovery Element (scroll down, you’ll see).

If multiple discovery elements are present on a page, the client may ask the user to choose which server it should connect to.

The Discovery Element

A discovery element is a micro-format for informing Okay clients where they should be looking for certain information. 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 should 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 Points to the server's room directory.
ok-register Points to the server’s registration endpoint.
ok-prefs Points to the server’s preferences endpoint.

initiation

Before a client can do anything with a server, it must first identify itself.

the directory

The Room Directory is a list of every room on the server. This list may be paginated.

groups & sections

rooms

messages

profiles

subscriptions

settings

pagination

critical reception

It’s okay.