Okay/Spec: Difference between revisions

Line 1:

{{#css:

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

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

}}{{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?~~~~

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

== in summary ==

Okay introduces a simple and flexible way to represent group chats within HTML documents, and some methods of interacting with them.

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

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

* 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 ~~use WebSockets~~ to ~~get a real-time feed of events that you’re interested in~~.

* You can receive events as they happen by [[Okay/Spec#subscriptions|subscribing]] to them.

* ~~Pretty much everything is represented as HTML over~~ the ~~wire~~. ~~This allows most~~ client ~~implementations skip~~ the ~~bit where they convert every message into HTML, while providing~~ a ~~stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser~~, and ~~letting you do really really stupid things with your messages.~~

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

* Authentication works by just signing every request ~~with a key that gets generated by the client on first use~~.

== the warning (Hot Chip album) ==

Line 16:

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

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

* What do we do about invalid HTML?

* Should room names be unique?

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

== connections ==

Line 42:

Line 43:

=== looking for stuff ===

=== linking to stuff ===

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

Line 58:

Line 57:

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

=== discovery ===

For a client to recognise a document as containing a space, it must:

Line 74:

Line 71:

==== 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#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="/register/" rel="ok-register">Registration</a>

<a href="/prefs/" rel="ok-prefs">Preferences</a>

</nav></syntaxhighlight>

</nav></syntaxhighlight>For an element to be considered valid <code>ok-space</code> markup, it must 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 must be ignored by the client. The inner text of the anchor elements is not significant and mustbe ignored by clients.

For an element to be considered valid <code>ok-space</code> markup, it must 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 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:

'''Key''': ◈ '''required''', ◇ '''optional''', ❖ '''can be specified multiple times'''

'''Key''': ◈ '''required''', ◇ '''optional''', ❖ '''can be specified multiple times'''

{| class="wikitable"

|+

Line 106:

Line 97:

==== linking to other spaces ====

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]] 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#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 118:

Line 108:

==== metadata ====

Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">

Line 137:

Line 126:

|-

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

|-

|<code>ok-subtitle</code>

|Any non-void element, <code><nowiki></nowiki></code> preferred.

|Any non-void element, <code><nowiki></nowiki></code>preferred.

|An extra bit of text that is displayed alongside the title in certain contexts.

|-

|<code>ok-description</code>

|Any non-void element, <code><nowiki></nowiki></code> preferred.

|Any non-void element, <code><nowiki></nowiki></code>preferred.

|A long description of what the space is about.

|}

Line 153:

Line 142:

== initiation ==

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

=== keys ===

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

The registration page allows clients to register their public key and [[Okay#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 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.

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

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>

<ul>

Line 180:

Line 164:

=== sections ===

A <code><section /></code> element denotes a '''section''', which allows severs to provide more structure to their room directory. Sections must 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 must be ignored by the client.

== rooms ==

== messages ==

== profiles ==

== subscriptions ==

== settings ==

== pagination ==

Many lists can be '''paginated''' when it would be impractical to send its entire contents. This is common in message lists and room directories if you're getting a bit silly with it.

== critical reception ==

It’s okay.

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

@@ Line 1: / Line 1: @@
 {{#css:
-#firstHeading::after { content: " The Specification."; }
+#firstHeading::after { content: " The Specification."; }}}{{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?</p>
+'''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?
 == in summary ==
+Okay introduces a simple and flexible way to represent group chats within HTML documents, and some methods of interacting with them.
-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/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.
-* A room is just a special URI which you can POST messages to and GET them back from at a later date.
+* 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 use WebSockets to get a real-time feed of events that you’re interested in.
+* You can receive events as they happen by [[Okay/Spec#subscriptions|subscribing]] to them.
-* Pretty much everything is represented as HTML over the wire. This allows most client implementations skip the bit where they convert every message into HTML, while providing a stable format for non-web platforms to convert into their own inferior representations. Other benefits include allowing users to browse most spaces with just their web browser, and letting you do really really stupid things with your messages.
+* 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.
-* Authentication works by just signing every request with a key that gets generated by the client on first use.
 == the warning (Hot Chip album) ==
@@ Line 16: / 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>
+* <s>What “server” means is kind of nebulous.</s>
 * What do we do about invalid HTML?
 * Should room names be unique?
+* check out webauthn. maybe it's a better idea than client side certs lol
 == connections ==
@@ Line 42: / Line 43: @@
 === looking for stuff ===
 === linking to stuff ===
 Links in Okay follow the same rules as in standard HTML.
@@ Line 58: / Line 57: @@
 == 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'''.
 === discovery ===
 For a client to recognise a document as containing a space, it <span class="must">must</span>:
@@ Line 74: / Line 71: @@
 ==== 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#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">
    <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>
+</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.
-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.
 A list of valid anchor <code>rel</code> attributes and their purposes is described below:
-'''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'''
+'''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>
 {| class="wikitable"
 |+
@@ Line 106: / Line 97: @@
 ==== linking to other spaces ====
 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]] 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#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 118: / Line 108: @@
 ==== metadata ====
 Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
      <h1 class="ok-title"></h1>
@@ Line 137: / Line 126: @@
 |-
 |<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.
 |-
 |<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.
 |-
 |<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.
 |}
@@ Line 153: / Line 142: @@
 == initiation ==
+A client <span class="must">must</span> register itself with a space before it can send messages to rooms.
-A client <span class="must">must</span> register itself with a space before it can send messages to rooms.
 === keys ===
 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 ===
 The registration page allows clients to register their public key and [[Okay#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 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.
-Here's an example of what a room directory might look like:
+Here's an example of what a room directory might look like:<syntaxhighlight lang="html"><main class="ok-rooms">
-<syntaxhighlight lang="html"><main class="ok-rooms">
    <h1>Rooms on This Server</h1>
    <ul>
@@ Line 180: / Line 164: @@
 === sections ===
 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.
 == rooms ==
 == messages ==
 == profiles ==
 == subscriptions ==
 == settings ==
 == pagination ==
 Many lists can be '''paginated''' when it would be impractical to send its entire contents. This is common in message lists and room directories if you're getting a bit silly with it.
 == critical reception ==
 It’s okay.
 [[Category:Pages that need things added to them]]