Okay/Spec: Difference between revisions

Line 27:

== in summary ==

Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and ~~fro~~ the ~~“Server”~~.

Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from the “Space”.

* A room is just a special URI which you can POST messages to and GET them back from at a later date.

Line 40:

== controversies ==

* what “server” means is kind of nebulous.

* <del>what “server” means is kind of nebulous.</del>

* what do we do about invalid html

== connection flow ==

A typical connection to an never before seen ~~server~~ usually goes like this:

A typical connection to an 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 [[Okay#discovery|discovery requirements]], it generates a new certificate and registers itself with the ~~server’s~~ registration endpoint;

* If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new certificate and registers itself with the spaces’s registration endpoint;

* Once everyone’s happy, the client can begin posting messages to rooms.

== ~~servers~~ ==

== spaces ==

== discovery ==

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 must meet all [[Okay#discovery|discovery requirements]] and must provide some metadata for clients to display, a [[Okay#rooms|room directory]], and preferences page.

For a client to recognise a URI as ~~an Okay protocol server~~, it must:

=== discovery ===

For a client to recognise a URI as a space, it must:

* Respond with 200 OK upon a GET request;

Line 61:

Line 64:

* Respond with a valid HTML document, -- TODO: define valid;

* Have the Access-Control-Allow-Origin header set to <code>*</code>;

* Contain a ~~Discovery Element (scroll down, you’ll see)~~.

* Contain a valid [[Okay#the element thereof|discovery element]].

If multiple discovery elements are present on a page, the client ~~may~~ ask the user to ~~choose~~ which ~~server~~ it should ~~connect to~~.

If multiple discovery elements are present on a page, the client should ask the user to select which space it should use.

=== the element thereof ===

==== the element thereof ====

A discovery element is a ~~micro-format for informing Okay clients where they should be looking for certain information~~. They look like this:

The '''discovery element''' provides a list of resources associated with the space. They look like this:

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

</nav></syntaxhighlight>

</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 should be a <code>< nav /></code> if you can help it. The discovery element must contain a number of anchor (<code><a /></code>) elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors must be ignored by the client. The inner text of the anchor elements is not significant and must be ignored by clients.

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 should be a <code><nav /></code> if you can help it. The discovery element must contain a number of anchor (<code><a /></code>) elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors 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 <code>rel</code> attributes and their purposes is described below:

Line 85:

Line 87:

|◈

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

|~~Points to the server~~'s [[Okay#the directory|room directory]].

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

|-

|◈

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

|~~Points to the server’s~~ registration ~~endpoint~~.

|The space's registration page.

|-

|◈

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

|~~Points to the server’s~~ preferences ~~endpoint~~.

|The space's preferences page.

|}

== initiation ==

A client must register itself with a ~~server~~ before it can send messages to rooms.

A client must register itself with a space before it can send messages to rooms.

== the directory ==

The '''Room Directory''' is a list of every room on the ~~server~~. 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#pagination|paginated]].

The path to the ~~server~~'s room directory must be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.

The path to the space's room directory must be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.

Here's an example of what a room directory might look like:

@@ Line 27: / Line 27: @@
 == in summary ==
-Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and fro the “Server”.
+Okay is a group chat protocol. You join “Rooms” which contain “People” who “Talk” by sending and receiving “Messages” to and from the “Space”.
 * A room is just a special URI which you can POST messages to and GET them back from at a later date.
@@ Line 40: / Line 40: @@
 == controversies ==
-* what “server” means is kind of nebulous.
+* <del>what “server” means is kind of nebulous.</del>
+* what do we do about invalid html
 == connection flow ==
-A typical connection to an never before seen server usually goes like this:
+A typical connection to an 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 [[Okay#discovery|discovery requirements]], it generates a new certificate and registers itself with the server’s registration endpoint;
+* If the response meets all the [[Okay#discovery|discovery requirements]], it generates a new certificate and registers itself with the spaces’s registration endpoint;
 * Once everyone’s happy, the client can begin posting messages to rooms.
-== servers ==
+== spaces ==
-== discovery ==
+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.
-For a client to recognise a URI as an Okay protocol server, it must:
+=== discovery ===
+For a client to recognise a URI as a space, it <span class="must">must</span>:
 * Respond with 200 OK upon a GET request;
@@ Line 61: / Line 64: @@
 * Respond with a valid HTML document, -- TODO: define valid;
 * Have the Access-Control-Allow-Origin header set to <code>*</code>;
-* Contain a Discovery Element (scroll down, you’ll see).
+* Contain a valid [[Okay#the element thereof|discovery element]].
-If multiple discovery elements are present on a page, the client may ask the user to choose which server it should connect to.
+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.
-=== the element thereof ===
+==== the element thereof ====
-A discovery element is a micro-format for informing Okay clients where they should be looking for certain information. They look like this:
+The '''discovery element''' provides a list of resources associated with the space. They look like this:
-<syntaxhighlight lang="html">
+<syntaxhighlight lang="html"><nav class=“ok-discover”>
-<nav class=“ok-discover”>
    <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>
+</nav></syntaxhighlight>
-</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.
+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:
@@ Line 85: / Line 87: @@
 |<span class="required">◈</span>
 |<span class="required"><code>'''ok-rooms'''</code></span>
-|Points to the server's [[Okay#the directory|room directory]].
+|The space's [[Okay#the directory|room directory]].
 |-
 |<span class="required">◈</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"><code>'''ok-prefs'''</code></span>
-|Points to the server’s preferences endpoint.
+|The space's preferences page.
 |}
 == initiation ==
-A client must register itself with a server before it can send messages to rooms.
+A client must register itself with a space before it can send messages to rooms.
 == the directory ==
-The '''Room Directory''' is a list of every room on the server. 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#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.
+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.
 Here's an example of what a room directory might look like: