Okay: Difference between revisions

From pronounmail wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{#css:Template:Colours.css}}{{#css:Template:Spec.css}}'''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?
{{#css:Template:Colours.css}}{{#css:Template:Spec.css}}{{#css:
#firstHeading::after { content: '“an hypertext chat protocol”'; }
}}<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>


== in summary ==
== in summary ==


Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from the “Space”.
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.
* 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.
* 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.
* 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.
* Every client is authenticated with a certificate that gets generated by the client on first use.
* Authentication works by just signing every request with a key that gets generated by the client on first use.
 
== the warning (Hot Chip album) ==
This standard is '''deeply unserious'''. It is also '''deeply in progress'''. Implement at your own peril.


== conventions ==
== conventions ==
Line 19: Line 24:
* what do we do about invalid html
* what do we do about invalid html


== connection flow ==
== connections ==
Connections in Okay <span class="should">should</span> 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:
A typical connection to a never before seen space usually goes like this:


* The user hands the client a URI to examine;
* The user hands the client a URI to examine;
* The client issues a GET request to the URI and examines the response;
* The client issues a GET request to the URI and examines the response;
* If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new certificate and registers itself with the spaces’s registration endpoint;
* If the response meets all the [[Okay#discovery|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.
* Once everyone’s happy, the client can begin posting messages to rooms.
== processing documents ==
Much of the Okay protocol involves retrieving documents and scanning them for special markup.
=== michaelformats ===
The Okay Standard introduces a number of HTML patterns known as '''michaelformats'''. These are identical in concept to (and heavily plagiarise from) [https://microformats.org/wiki/Main_Page microformats].
=== looking for stuff ===
=== linking to stuff ===
Links in Okay follow the same rules as in standard HTML.
When a client encounters a URI with a fragment, it <span class="must">must</span> search for an element with a matching <code>id</code> in the linked document. If the specified element is present, the client <span class="mustnt">must not</span> scan the document for the desired markup, and instead consider the linked element to be the desired markup. If multiple instances of the same <code>id</code> exist in the document, the client <span class="must">must</span> ignore all but the first instance. todo: make this make sense


== spaces ==
== 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 <span class="must">must</span> meet all [[Okay#discovery|discovery requirements]] and <span class="must">must</span> provide some metadata for clients to display, a [[Okay#rooms|room directory]], and preferences page.
Conceptually, a '''space''' is an isolated container that stores room state and user data. They are each represented by a [[Okay#ok-space|HTML element]] which provides URIs for clients to send their requests to (for example, its [[Okay#rooms|room directory]] or [[Okay#initiation|registration page]]). The URI of the document that contains this is called the space's '''root URI'''.


=== discovery ===
=== discovery ===


For a client to recognise a URI as a space, it <span class="must">must</span>:
For a client to recognise a document as containing a space, it <span class="must">must</span>:


* Respond with 200 OK upon a GET request;
* Respond with 200 OK upon a GET request;
Line 40: Line 60:
* Respond with a valid HTML document, -- TODO: define valid;
* Respond with a valid HTML document, -- TODO: define valid;
* Have the Access-Control-Allow-Origin header set to <code>*</code>;
* Have the Access-Control-Allow-Origin header set to <code>*</code>;
* Contain a valid [[Okay#the element thereof|discovery element]].
* Contain valid [[Okay#the element thereof|ok-space]] markup.


If multiple discovery elements are present on a page, the client <span class="should">should</span> ask the user to select which space it should use.
If a document contains multiple spaces, the client <span class="should">should</span> prompt the user to select which space it should use.


==== the element thereof ====
==== ok-space ====


The '''discovery element''' provides a list of resources associated with the space. They look like this:
Spaces are declared using the '''ok-space''' [[Okay#michaelformats|michaelformat]]. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:


<syntaxhighlight lang="html"><nav class=“ok-discover”>
<syntaxhighlight lang="html"><nav class=“ok-space”>
  <h1>This is an Okay space</h1>
   <a href=“/rooms/” rel=“ok-rooms”>Rooms</a>
   <a href=“/rooms/” rel=“ok-rooms”>Rooms</a>
   <a href=“/register/” rel=“ok-register”>Registration</a>
   <a href=“/register/” rel=“ok-register”>Registration</a>
Line 54: Line 75:
</nav></syntaxhighlight>
</nav></syntaxhighlight>


The discovery element is defined as any element with the <code>ok-discover</code> class. Any non-void element can be the discovery element, but it really <span class="should">should</span> be a <code><nav /></code> if you can help it. The discovery element <span class="must">must</span> contain a number of anchor (<code><a /></code>) elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.
For an element to be considered valid <code>ok-space</code> markup, it <span class="must">must</span> be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.


A list of valid anchor <code>rel</code> attributes and their purposes is described below:
A list of valid anchor <code>rel</code> attributes and their purposes is described below:


'''Key''': <span class="required">◈ '''Required'''</span>, <span class="optional>◇ '''Optional'''</span>, <span class="multiple">❖ '''Can be specified multiple times'''
'''Key''': <span class="required"><span class="symbol">◈</span> '''required'''</span>, <span class="optional><span class="symbol">◇</span> '''optional'''</span>, <span class="multiple"><span class="symbol">❖</span> '''can be specified multiple times'''
{| class="wikitable"
{| class="wikitable"
|+
|+
|<span class="required">◈</span>
|<span class="required"><span class="symbol">◈</span></span>
|<span class="required"><code>'''ok-rooms'''</code></span>
|<span class="required"><code>'''ok-rooms'''</code></span>
|The space's [[Okay#the directory|room directory]].
|The space's [[Okay#the directory|room directory]].
|-
|-
|<span class="required">◈</span>
|<span class="required"><span class="symbol">◈</span></span>
|<span class="required"><code>'''ok-register'''</code></span>
|<span class="required"><code>'''ok-register'''</code></span>
|The space's registration page.
|The space's registration page.
|-
|-
|<span class="required">◈</span>
|<span class="required"><span class="symbol">◈</span></span>
|<span class="required"><code>'''ok-prefs'''</code></span>
|<span class="required"><code>'''ok-prefs'''</code></span>
|The space's preferences page.
|The space's preferences page.
|}
|}
==== linking to other spaces ====
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" -->
<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></syntaxhighlight>
==== metadata ====
Spaces <span class="may">may</span>/<span class="should">should</span> provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
    <h1 class="title"></h1>
    <p class="subtitle"></p>
    <p class="description"></p>
    <img class="icon" src="">
    <!-- ... -->
</nav></syntaxhighlight>


== initiation ==
== initiation ==


A client must register itself with a space before it can send messages to rooms.   
A client <span class="must">must</span> register itself with a space before it can send messages to rooms.   
 
=== keys ===
 
When registering with a space, a client <span class="should">should</span> 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 [[Okay#profiles|profile]] with the space.


== the directory ==
== the directory ==
The '''Room Directory''' is a list of every room contained within the space. This list may be [[Okay#pagination|paginated]].


The path to the space's room directory <span class="must">must</span> be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.
The '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay#pagination|paginated]].
 
The URI of the space's room directory <span class="must">must</span> be linked in its [[Okay#ok-space|ok-space]] element using the <code>ok-rooms</code> rel value.


Here's an example of what a room directory might look like:
Here's an example of what a room directory might look like:
Line 90: Line 142:
     <li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>
     <li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>
   </ul>
   </ul>
</main></syntaxhighlight>
</main></syntaxhighlight>A room directory is still just a rat in a cage.


=== sections ===
=== sections ===
Clients <span class="may">may</span> recognise a <code><section /></code> 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.
 
A <code><section /></code> element denotes a '''section''', which allows severs to provide more structure to their room directory. Sections <span class="must">must</span> 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 <span class="must">must</span> be ignored by the client.


== rooms ==
== rooms ==


== messages ==
== messages ==
== profiles ==
== profiles ==
== subscriptions ==
== subscriptions ==


Line 104: Line 159:


== pagination ==
== 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 ==
== critical reception ==
It’s okay.
It’s okay.


[[Category:Pages that need things added to them]] [[Category:Pages with some amount of information in them]]
[[Category:Pages that need things added to them]] [[Category:Pages with some amount of information in them]]

Latest revision as of 09:53, 1 March 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.

the warning (Hot Chip album)

This standard is deeply unserious. It is also deeply in progress. Implement at your own peril.

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 a 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.

processing documents

Much of the Okay protocol involves retrieving documents and scanning them for special markup.

michaelformats

The Okay Standard introduces a number of HTML patterns known as michaelformats. These are identical in concept to (and heavily plagiarise from) microformats.

looking for stuff

linking to stuff

Links in Okay follow the same rules as in standard HTML.

When a client encounters a URI with a fragment, it must search for an element with a matching id in the linked document. If the specified element is present, the client must not scan the document for the desired markup, and instead consider the linked element to be the desired markup. If multiple instances of the same id exist in the document, the client must ignore all but the first instance. todo: make this make sense

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 michaelformat. 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 may/should 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 URI of the space's room directory must be linked in its ok-space element using 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>

A room directory is still just a rat in a cage.

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.