Okay: Difference between revisions
No edit summary |
you're so wrong about that actually |
||
Line 79: | Line 79: | ||
==== linking to other spaces ==== | ==== linking to other spaces ==== | ||
A document | A document can direct clients to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client <span class="must">must</span> scan the linked document for valid <code>ok-space</code> markup, but it <span class="mustnt">must not</span> follow any further links or anchors with the <code>rel="ok-space"</code> attribute. | ||
The URI provided <span class="may">may</span> include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element <span class="must">must</span> be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client <span class="mustnt">must not</span> scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html"><!-- link to a space with the id "space" --> | The URI provided <span class="may">may</span> include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element <span class="must">must</span> be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client <span class="mustnt">must not</span> scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html"><!-- link to a space with the id "space" --> | ||
Line 90: | Line 90: | ||
==== metadata ==== | ==== metadata ==== | ||
Spaces | Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space"> | ||
<h1 class="title"></h1> | <h1 class="title"></h1> | ||
<p class="subtitle"></p> | <p class="subtitle"></p> |
Revision as of 13:16, 28 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 connect to "Spaces" which contain “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from 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.
- Pretty much everything is 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. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.
- Authentication works by just signing every request with a key 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
connections
Connections in Okay should happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).
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 key pair and registers itself with the space’s registration endpoint;
- Once everyone’s happy, the client can begin posting messages to rooms.
spaces
Conceptually, a space is an isolated container that stores room state and user data. They are each represented by a HTML element which provides URIs for clients to send their requests to (for example, its room directory or registration page). The URI of the document that contains this is called the space's root URI.
discovery
For a client to recognise a document as containing 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 valid ok-space markup.
If a document contains multiple spaces, the client should prompt the user to select which space it should use.
ok-space
Spaces are declared using the ok-space micro-format. Upon retrieving a document, the client must scan for elements with the ok-space
class, as well as links and anchors with the ok-space
rel attribute. Here's an example of valid ok-space
markup:
<nav class=“ok-space”>
<h1>This is an Okay space</h1>
<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>
For an element to be considered valid ok-space
markup, it must be a non-void element (ideally a <nav />
) with the ok-space
class and contain anchor elements with valid rel
and href
attributes. Any invalid anchors or elements not specified in the format 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. |
linking to other spaces
A document can direct clients to another document containing a space using an <a />
or <link />
element with the rel="ok-space"
attribute. The client must scan the linked document for valid ok-space
markup, but it must not follow any further links or anchors with the rel="ok-space"
attribute.
The URI provided may include a fragment component to specify which element the client should treat as ok-space markup (e.g., https://example.com/#my-elem
). The linked element must be valid ok-space
markup. If the fragment is specified and the corresponding element is present in the linked document, the client must not scan any other part of the document for ok-space
markup.
<!-- link to a space with the id "space" -->
<link rel="ok-space" href="https://example.ok/#space" />
<!-- anchors work, too. this one forces the client to rummage around
for spaces like an animal -->
<a rel="ok-space" href="https://benfoldsfive.example/">
chat in the official Ben Folds Five space!!!
</a>
metadata
Spaces can provide metadata about themselves to help users identify them.
<nav class="ok-space">
<h1 class="title"></h1>
<p class="subtitle"></p>
<p class="description"></p>
<img class="icon" src="">
<!-- ... -->
</nav>
initiation
A client must register itself with a space before it can send messages to rooms.
keys
When registering with a space, a client should transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.
registration the page
The registration page allows clients to register their public key and profile with the space.
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
A <section />
element denotes a section, which allows severs to provide more structure to their room directory. Sections must have a heading of any level as a direct descendant and one or more room links. Anything within the section that isn't a header or room link must be ignored by the client.
rooms
messages
profiles
subscriptions
settings
pagination
Many lists can be paginated when it would be impractical to send its entire contents. This is common in message lists and room directories if you're getting a bit silly with it.
critical reception
It’s okay.