Okay/Spec: Difference between revisions
No edit summary |
|||
| (9 intermediate revisions by one other user not shown) | |||
| Line 3: | Line 3: | ||
}}{{spec|Okay.}} | }}{{spec|Okay.}} | ||
<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? | '''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 == | ||
| Line 21: | Line 23: | ||
== controversies == | == controversies == | ||
* <s>What “server” means is kind of nebulous.</s> | * <s>What “server” means is kind of nebulous.</s> | ||
* What do we do about invalid HTML? | * What do we do about invalid HTML? | ||
| Line 33: | Line 34: | ||
* 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 checks the response against the [[Okay#discovery|discovery requirements]]; | * 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#registration|registers]] itself; | * 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. | * Once everyone’s happy, the client can begin posting messages to rooms. | ||
| Line 69: | Line 70: | ||
== spaces == | == spaces == | ||
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'''. | 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'''. | ||
=== discovery === | === discovery === | ||
| Line 78: | Line 79: | ||
* Respond with a valid HTML document; <span class="todo">define valid</span> | * 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 valid [[Okay#the element thereof|ok-space]] markup. | * 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. | If a document contains multiple spaces, the client <span class="should">should</span> prompt the user to select which space it should use. | ||
==== ok-space ==== | ==== ok-space ==== | ||
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-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"> | ||
<h1>This is an Okay space</h1> | <h1>This is an Okay space</h1> | ||
<a href="/rooms/" rel="ok-rooms">Rooms</a> | <a href="/rooms/" rel="ok-rooms">Rooms</a> | ||
| Line 97: | Line 98: | ||
|<span class="required"><span class="symbol">◈</span></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/Spec#the directory|room directory]]. | ||
|- | |- | ||
|<span class="required"><span class="symbol">◈</span></span> | |<span class="required"><span class="symbol">◈</span></span> | ||
| Line 111: | Line 112: | ||
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. | 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]]<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" --> | 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" /> | <link rel="ok-space" href="https://example.ok/#space" /> | ||
<!-- anchors work, too. thanks to the lack of fragment (the bit after the #), | <!-- anchors work, too. thanks to the lack of fragment (the bit after the #), | ||
| Line 138: | Line 139: | ||
|- | |- | ||
|<code>ok-title</code> | |<code>ok-title</code> | ||
|Any non-void element, <code><nowiki><h1 /></nowiki></code>preferred. | |Any non-void element, <code><nowiki><h1 /></nowiki></code> preferred. | ||
|What the space is called in common parlance. | |What the space is called in common parlance. | ||
|- | |- | ||
|<code>ok-subtitle</code> | |<code>ok-subtitle</code> | ||
|Any non-void element, <code><nowiki><p /></nowiki></code>preferred. | |Any non-void element, <code><nowiki><p /></nowiki></code> preferred. | ||
|An extra bit of text that is displayed alongside the title in certain contexts. | |An extra bit of text that is displayed alongside the title in certain contexts. | ||
|- | |- | ||
|<code>ok-description</code> | |<code>ok-description</code> | ||
|Any non-void element, <code><nowiki><p /></nowiki></code>preferred. | |Any non-void element, <code><nowiki><p /></nowiki></code> preferred. | ||
|A long description of what the space is about. | |A long description of what the space is about. | ||
|} | |} | ||
| Line 154: | Line 155: | ||
== initiation == | == initiation == | ||
A client <span class="must">must</span> register itself with a space before it can | A client <span class="must">must</span> register itself with a space before it can perform most actions. | ||
=== keys === | === keys === | ||
| Line 160: | Line 161: | ||
=== registration === | === registration === | ||
The registration page allows clients to register their public key and [[Okay#profiles|profile]] with the space. | The registration page allows clients to register their public key and [[Okay/Spec#profiles|profile]] with the space. | ||
== directory == | |||
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"> | 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" | <li><a href="/rooms/1" rel="ok-room">General</a></li> | ||
<li><a href="/rooms/evil" | <li><a href="/rooms/evil" rel="ok-room">Evildoing Room (evil)</a></li> | ||
</ul> | </ul> | ||
</main></syntaxhighlight>A room directory is still just a rat in a cage. | </main></syntaxhighlight>A room directory is still just a rat in a cage. | ||