Okay/Spec: Difference between revisions

Line 5:

== in summary ==

Okay is a group chat protocol. You connect to "'''Spaces'''" which contain “'''Rooms'''” which contain “'''People'''” who “'''Talk'''” by sending and receiving “'''Messages'''” to and from the “'''Server'''”.

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

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

Line 17:

== conventions ==

The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may”, and “optional” 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).

The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may”, and “optional” 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).

== controversies ==

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

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

* ~~what~~ do we do about invalid ~~html~~

* What do we do about invalid HTML?

== connections ==

Line 46:

Links in Okay follow the same rules as in standard HTML.

When a client encounters a URI with a fragment, it must search for an element with a matching <code>id</code> in the linked document. If the specified element is present, the client must not 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 must ignore all but the first instance. todo: make this make sense

When a client encounters a URI with a fragment, it must search for an element with a matching <code>id</code> in the linked document. If the specified element is present, the client must not 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 must ignore all but the first instance. make this make sense

== talking to servers ==

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

=== discovery ===

Line 61:

Line 60:

* Respond with 200 OK upon a GET request;

* Have a Content-Type of text/html;

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

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

Line 71:

Line 70:

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:

<h1>This is an Okay space</h1>

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

Line 144:

Line 143:

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.

todo: class name bikeshedding

class name bikeshedding

== initiation ==

Line 152:

Line 151:

=== keys ===

When registering with a space, a client should transparently generate a key pair (~~TODO:~~ what type(s)?) and store it for use in subsequent requests.

When registering with a space, a client should transparently generate a key pair (what type(s)?) and store it for use in subsequent requests.

=== registration ===

@@ Line 5: / Line 5: @@
 == in summary ==
-Okay is a group chat protocol. You connect to "'''Spaces'''" which contain “'''Rooms'''” which contain “'''People'''” who “'''Talk'''” by sending and receiving “'''Messages'''” to and from the “'''Server'''”.
+Okay is a group chat protocol. You connect to “'''Spaces'''” which contain “'''Rooms'''” which contain “'''People'''” who “'''Talk'''” by sending and receiving “'''Messages'''” to and from the “'''Server'''”.
 * A room is just a special URI which you can POST messages to and GET them back from at a later date.
@@ Line 17: / Line 17: @@
 == 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).
+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).
 == controversies ==
-* <del>what “server” means is kind of nebulous.</del>
+* <del>What “server” means is kind of nebulous.</del>
-* what do we do about invalid html
+* What do we do about invalid HTML?
 == connections ==
@@ Line 46: / Line 46: @@
 Links in Okay follow the same rules as in standard HTML.
-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. todo: make this make sense
+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>
 == talking to servers ==
 == 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#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'''.
 === discovery ===
@@ Line 61: / Line 60: @@
 * Respond with 200 OK upon a GET request;
 * Have a Content-Type of text/html;
-* 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>;
 * Contain valid [[Okay#the element thereof|ok-space]] markup.
@@ Line 71: / Line 70: @@
 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”>
+<syntaxhighlight lang="html"><nav class="ok-space">
    <h1>This is an Okay space</h1>
-   <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>
@@ Line 144: / Line 143: @@
 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.
-todo: class name bikeshedding
+<span class="todo">class name bikeshedding</span>
 == initiation ==
@@ Line 152: / Line 151: @@
 === keys ===
-When registering with a space, a client <span class="should">should</span> transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.
+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.
 === registration ===