Okay/Spec: Difference between revisions

Line 33:

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

Line 69:

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

Line 78:

* Respond with a valid HTML document; define valid

* 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 should prompt the user to select which space it should use.

==== ok-space ====

Spaces are declared using the '''ok-space''' [[Okay#michaelformats|michaelformat]]. Upon retrieving a document, the client must 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 must 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>

Line 97:

|◈

|<code>'''ok-rooms'''</code>

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

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

|-

|◈

Line 111:

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 must scan the linked document for valid <code>ok-space</code> markup, but it must not follow any further links or anchors with the <code>rel="ok-space"</code> attribute.

The URI provided may 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 must be valid <code>ok-space</code> 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 <code>ok-space</code> markup.<syntaxhighlight lang="html">

The URI provided may 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 must be valid <code>ok-space</code> 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 <code>ok-space</code> markup.<syntaxhighlight lang="html">

<!-- anchors work, too. thanks to the lack of fragment (the bit after the #),

Line 160:

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

== the directory ==

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

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

The URI of the space's room directory must be linked in its [[Okay#ok-space|ok-space]] element using the <code>ok-rooms</code> rel value.

The URI of the space's room directory must be linked in its [[Okay/Spec#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:<syntaxhighlight lang="html"><main class="ok-rooms">

@@ Line 33: / Line 33: @@
 * 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.
@@ Line 69: / Line 69: @@
 == 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 ===
@@ Line 78: / Line 78: @@
 * Respond with a valid HTML document; <span class="todo">define valid</span>
 * 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.
 ==== 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>
    <a href="/rooms/" rel="ok-rooms">Rooms</a>
@@ Line 97: / Line 97: @@
 |<span class="required"><span class="symbol">◈</span></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>
@@ Line 111: / Line 111: @@
 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" />
 <!-- anchors work, too. thanks to the lack of fragment (the bit after the #),
@@ Line 160: / Line 160: @@
 === 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.
 == the directory ==
-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 '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay/Spec#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.
+The URI of the space's room directory <span class="must">must</span> be linked in its [[Okay/Spec#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:<syntaxhighlight lang="html"><main class="ok-rooms">