Okay/Spec: Difference between revisions

{{#css:

#firstHeading::after { content: " The Specification."; }

}}{{spec|Okay.}}

'''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?

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.

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

* Should room names be unique?

* check out webauthn. maybe it's a better idea than client side certs lol

Connections in Okay <span class="should">should</span> happen over HTTPS. Plaintext HTTP is acceptable for testing purposes.

A typical connection to a never before seen space usually goes like this:

* The client issues a GET request to the URI and checks the response against the [[Okay/Spec#discovery|discovery requirements]];

* 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 ===

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.

As an example, each of these elements are functionally equivalent:<syntaxhighlight lang="html"><!-- a room directory, rendered inline -->

<div class="ok-rooms">

<!-- a room directory, linked with an anchor 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].

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>

Sometimes you need to send stuff to the server. That's fine. That's okay. You'll be okay.

Forms come in various forms.  

== spaces ==

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

* Have a MIME type of <code>text/html</code>;

* Respond with a valid HTML document; <span class="todo">define valid</span>

* Contain valid [[Okay/Spec#the element thereof|ok-space]] markup.

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

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">

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

'''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>

|<span class="required"><span class="symbol">◈</span></span>

|The space's [[Okay/Spec#the directory|room directory]].

|<span class="required"><span class="symbol">◈</span></span>

|The space's registration page.

|<span class="required"><span class="symbol">◈</span></span>

|The space's preferences page.

 

 

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" -->

 

|A long description of what the space is about.

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

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.

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.

Here's an example of what a room directory might look like:<syntaxhighlight lang="html"><main class="ok-rooms">

     <li><a href="/rooms/1" rel="ok-room">General</a></li>

     <li><a href="/rooms/evil" rel="ok-room">Evildoing Room (evil)</a></li>

</main></syntaxhighlight>A room directory is still just a rat in a cage.

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.

[[Category:Pages that need things added to them]]