pronounmail wiki

Okay/Spec: Difference between revisions

← Older edit
VisualWikitext
No edit summary
 
(72 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{#css:Template:Colours.css}}{{#css:
{{#css:
span.required, .required code {
#firstHeading::after { content: " The Specification."; }
color: var(--colour-bubblegum-700);
}}{{spec|Okay.}}
}


span.optional, .optional code {
<p class="lede">
color: var(--colour-ectoplasm-700);
'''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>


span.multiple, .multiple code {
== in summary ==
color: var(--colour-yellow-700);
The '''Okay''' standard introduces a simple and flexible way to represent group chats within HTML documents, and some methods of interacting with them.
}
 
* ''[[Okay/Spec#messages|Messages]]'' are sent to ''[[Okay/Spec#rooms|Rooms]]'', which are organised into ''[[Okay/Spec#spaces|Spaces]]''.
* Like all good protocols, all communication happens over HTTP(S) and WebSockets.  
* All data in Okay is formatted according to standardised HTML patterns (much like how [https://microformats.org/wiki/about Microformats] work). We call these [[Okay/Spec#michaelformats|Michaelformats]] because I thought it would be funny.
* You can receive events as they happen by [[Okay/Spec#subscriptions|subscribing]] to them.
* Authentication uses the magic of client-side certificates. When a user adds a space, the client registers itself with the server using a fresh certificate, and then uses that to sign each subsequent request.
 
== 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 “<span class="must">must</span>”, “<span class="mustnt">must not</span>”, “<span class="must">required</span>”, “<span class="must">shall</span>”, “<span class="mustnt">shall not</span>”, “<span class="should">should</span>”, “<span class="shouldnt">should not</span>”, “<span class="should">recommended</span>”, “<span class="may">may</span>”, and “<span class="may">optional</span>” in this document are to be interpreted as described in [https://datatracker.ietf.org/doc/bcp14 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).


ul {
== controversies ==
  list-style-type: "❊ ";
* <s>What “server” means is kind of nebulous.</s>
  list-style-image: none;
* What do we do about invalid HTML?
}
* Should room names be unique?
* check out webauthn. maybe it's a better idea than client side certs lol


.must { color: var(--colour-bubblegum-700); font-weight: bold; }
== connections ==
.mustnt { color: var(--colour-aubergine-700); font-weight: bold; }
Connections in Okay <span class="should">should</span> happen over HTTPS. Plaintext HTTP is acceptable for testing purposes.
.should { color: var(--colour-orange-700); font-weight: bold; }
.shouldnt { color: var(--colour-weezer-700); font-weight: bold; }
.may { color: var(--colour-ectoplasm-700); font-weight: bold; }


}}'''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?
A typical connection to a never before seen space usually goes like this:


== in summary ==
* The user hands the client a URI to examine;
* The client issues a GET request to the URI and checks the response against the [[Okay/Spec#discovery|discovery requirements]];
* If the response meets all requirements, it generates a new key pair and [[Okay/Spec#registration|registers]] itself;
* Once everyone’s happy, the client can begin posting messages to rooms.


Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and fro the “Server”.
== processing documents ==
Much of the Okay protocol involves retrieving documents and scanning them for special markup.


* A room is just a special URI which you can POST messages to and GET them back from at a later date.
=== michaelformats ===
* You can use WebSockets to get a real-time feed of events that you’re interested in.
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].
* 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 ==
=== looking for stuff ===
=== linking to stuff ===
Unless otherwise specified, michaelformats can be included inline or '''linked''' in a <code><a/></code> or <code><link/></code> element, using the michaelformat's name as the <code>rel</code> attribute.


The key words "<span class="must">must</span>", "<span class="mustnt">must not</span>", "<span class="must">required</span>", "<span class="must">shall</span>", "<span class="mustnt>shall not</span>", "<span class="should">should</span>", "<span class="shouldnt">should not</span>", "<span class="should">recommended</span>", "<span class="may">may</span>", and "<span class="may">optional</span>" in this document are to be interpreted as described in [https://datatracker.ietf.org/doc/bcp14 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).
As an example, each of these elements are functionally equivalent:<syntaxhighlight lang="html"><!-- a room directory, rendered inline -->
<div class="ok-rooms">
    <!-- ... -->
</div>


== todo list ==
<!-- a room directory, linked with an anchor tag -->
<a href="/rooms/" rel="ok-rooms">Room Directory</a>


* what “server” means is kind of nebulous.
<!-- a room directory, linked with an link tag -->
<link href="/rooms/" rel="ok-rooms"></syntaxhighlight>The value of the <code>href</code> attribute <span class="must">must</span> be a ''valid URL potentially surrounded by spaces'', as [https://html.spec.whatwg.org/multipage/urls-and-fetching.html#valid-url-potentially-surrounded-by-spaces defined in the HTML standard].  


== connection flow ==
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. <span class="todo">make this make sense</span>


A typical connection to an never before seen server usually goes like this:
== sending stuff ==
Sometimes you need to send stuff to the server. That's fine. That's okay. You'll be okay.


* The user hands the client a URI to examine;
=== forms ===
* The client issues a GET request to the URI and examines the response;
Forms come in various forms.  
* If the response meets all the [[Okay#discovery|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.


== servers ==
Servers must accept form responses as <code>application/x-www-form-urlencoded</code> or <code>application/json</code>.


== discovery ==
== spaces ==
Conceptually, a '''space''' is an isolated container that stores room state and user data. They are each represented by a [[Okay/Spec#ok-space|HTML element]] which provides URIs for clients to send their requests to (for example, its [[Okay/Spec#rooms|room directory]] or [[Okay/Spec#initiation|registration page]]). The URI of the document that contains this is called the space’s '''root URI'''.


For a client to recognise a URI as an Okay protocol server, it must:
=== discovery ===
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;
* Have a Content-Type of text/html;
* Have a MIME type of <code>text/html</code>;
* Respond with a valid HTML document, -- TODO: define valid;
* Respond with a valid HTML document; <span class="todo">define valid</span>
* Have the Access-Control-Allow-Origin header set to <code>*</code>;
* Have the Access-Control-Allow-Origin header set to <code>*</code>;
* Contain a Discovery Element (scroll down, you’ll see).
* Contain valid [[Okay/Spec#the element thereof|ok-space]] markup.
If multiple discovery elements are present on a page, the client may ask the user to choose which server it should connect to.


=== the element thereof ===
If a document contains multiple spaces, the client <span class="should">should</span> prompt the user to select which space it should use.


A discovery element is a micro-format for informing Okay clients where they should be looking for certain information. They look like this:
==== ok-space ====
 
Spaces are declared using the '''ok-space''' [[Okay/Spec#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/Spec#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-space">
<syntaxhighlight lang="html">
  <h1>This is an Okay space</h1>
<nav class=“ok-discover”>
   <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>
   <a href="/prefs/" rel="ok-prefs">Preferences</a>
   <a href=“/prefs/” rel=“ok-prefs”>Preferences</a>
</nav></syntaxhighlight>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.
</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.


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'''</span>
{| 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>
|Points to the server's [[Okay#the directory|room directory]].
|The space's [[Okay/Spec#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>
|Points to the server’s registration endpoint.
|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>
|Points to the server’s preferences endpoint.
|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/Spec#ok-space|ok-space]]<nowiki/>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. thanks to the lack of fragment (the bit after the #),
    this link 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 can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
    <h1 class="ok-title"></h1>
    <p class="ok-subtitle"></p>
    <p class="ok-description"></p>
    <img class="ok-icon" src="">
    <!-- ... -->
</nav></syntaxhighlight>Space metadata can be declared anywhere within the ok-space element, using the class names given below:
{| class="wikitable"
|+
!Class Name
!Tag
!Purpose
|-
|<code>ok-icon</code>
|<code><img /></code> or <code><picture /></code>.
|An image to represent the space visually. These are typically square and rendered at small sizes.
|-
|<code>ok-title</code>
|Any non-void element, <code><nowiki><h1 /></nowiki></code> preferred.
|What the space is called in common parlance.
|-
|<code>ok-subtitle</code>
|Any non-void element, <code><nowiki><p /></nowiki></code> preferred.
|An extra bit of text that is displayed alongside the title in certain contexts.
|-
|<code>ok-description</code>
|Any non-void element, <code><nowiki><p /></nowiki></code> preferred.
|A long description of what the space is about.
|}
Clients may strip out child elements for some or all of the metadata elements, but should retain any text content from within the stripped elements.
<span class="todo">class name bikeshedding</span>


== initiation ==
== initiation ==
A client <span class="must">must</span> register itself with a space before it can perform most actions.
=== keys ===
When registering with a space, a client <span class="should">should</span> transparently generate a key pair (<span class="todo">what type(s)?</span>) and store it for use in subsequent requests.


A client must register itself with a server before it can send messages to rooms.
=== registration ===
The registration page allows clients to register their public key and [[Okay/Spec#profiles|profile]] with the space.  


== the directory ==
== directory ==
The '''Room Directory''' is a list of every room on the server. This list may be [[Okay#pagination|paginated]].
The '''room directory''' is represented using the <code>ok-rooms</code> [[Okay/Spec#michaelformats|michaelformat]]. It contains the list of every room in a space. This list <span class="may">may</span> be [[Okay/Spec#pagination|paginated]].


The path to the server'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.
A space's room directory <span class="must">must</span> be present in its [[Okay/Spec#ok-space|ok-space]] element, either [[Okay/Spec#linking to stuff|linked]] using the <code>ok-rooms</code> rel value or included inline.


Here's an example of what a room directory might look like:
Each room in the space <span class="must">must</span> be linked with a single <code><a /></code> element with the <code>ok-room</code> rel value. Rooms <span class="mustnt">must not</span> be included inline in the room directory.
<syntaxhighlight lang="html"><main class="ok-rooms">
 
Here's an example of what a room directory might look like:<syntaxhighlight lang="html"><main class="ok-rooms">
   <h1>Rooms on This Server</h1>
   <h1>Rooms on This Server</h1>
   <ul>
   <ul>
     <li><a href="/rooms/1" class="ok-room">General</a></li>
     <li><a href="/rooms/1" rel="ok-room">General</a></li>
     <li><a href="/rooms/evil" class="ok-room">Evildoing Room (evil)</a></li>
     <li><a href="/rooms/evil" rel="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 ==
== settings ==
== settings ==
== 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 with some amount of information in them]]
[[Category:Pages that need things added to them]]
Retrieved from "https://wiki.pronounmail.com/wiki/Okay/Spec"