From a4d656a5a270471fbb8dd5e9602d9181c4e9e1ce Mon Sep 17 00:00:00 2001
From: Vitor Pamplona <vitor@vitorpamplona.com>
Date: Thu, 4 Jan 2024 11:26:50 -0500
Subject: [PATCH] declaring types in the relay protocol messages

---
 01.md | 53 ++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/01.md b/01.md
index a38ac1d..5823119 100644
--- a/01.md
+++ b/01.md
@@ -124,17 +124,22 @@ Subscriptions stay indefinitely open until either side closes the subscription o
 
 ### Subscription Requests
 
-To open and update, and close subscriptions, Clients MUST use the following formats: 
-  * `["REQ", <subscription_id>, <filter1>, <filter2>, ...]`,
-  * `["CLOSE", <subscription_id>]`
+To request or update a subscription, send a `REQ` message with the format 
 
-`REQ` requests events and subscribes to new updates. A `REQ` message on an existing subscription overrides the previous subscription.
+```js 
+["REQ", <string subscription_id>, <string filter1>, <string filter2>, ...]
+```
 
-`CLOSE` stops the respective subscription.
+To stop receiving events from a subscription: 
+```js 
+["CLOSE", <string subscription_id>]
+```
 
-`<subscription_id>` is a non-empty string with a maximum length of 64 chars. Relays MUST manage `<subscription_id>`s independently for each WebSocket connection. `<subscription_id>`s are not globally unique. 
+ A `REQ` message on an existing subscription overrides the previous subscription.
 
-`<filterX>` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes:
+`subscription_id` is a non-empty string with a maximum length of 64 chars. Relays MUST manage `<subscription_id>`s independently for each WebSocket connection. `<subscription_id>`s are not globally unique. 
+
+`filterX` is a stringified JSON object that determines what events will be sent in that subscription, it can have the following attributes:
 
 ```js
 {
@@ -164,27 +169,39 @@ The `limit` attribute informs the maximum number of events to return, sorted by
 
 ### Subscription Responses
 
-Relays send 3 types of messages during a subscription:  
+The `EVENT` message is used to send events requested by clients:
 
-  * `["EVENT", <subscription_id>, <JSON-serialized string of the event>]`
-  * `["EOSE", <subscription_id>]`, 
-  * `["CLOSED", <subscription_id>, <prefix>:<message>]`
+```js 
+["EVENT", <string subscription_id>, <string JSON-serialized event>]
+```
 
-The `EVENT` message is used to send events requested by clients. 
+Once all matching events are sent, an `EOSE` message follows to indicate the _end of stored events_ and the beginning of events newly received in real-time. 
 
-`EOSE` indicates the _end of stored events_ and the beginning of events newly received in real-time. 
+```js 
+["EOSE", <string subscription_id>]
+```
 
-`CLOSED` messages MUST be sent in response to a `REQ` when the relay refuses to fulfill it. It can also be sent when a relay decides to kill a subscription on its side before a client has disconnected or sent a `CLOSE`. The message MUST be a string formed by a machine-readable single-word prefix followed by a `:` and then a human-readable message.
+`CLOSED` messages can be when the relay refuses to fulfill a `REQ` or when it decides to kill a subscription before a client has disconnected or sent a `CLOSE`, a `CLOSED` message is sent: 
+
+```js 
+["CLOSED", <string subscription_id>, <string prefix:message>]
+```
+
+The message MUST be a string formed by a machine-readable single-word prefix followed by a `:` and then a human-readable message.
 
 ## Publishing
 
 To send an event to the Relay, Clients send a broadcast message in the format: 
 
-  * `["EVENT", <JSON-serialized string of the event>]`
+```js 
+["EVENT", <string JSON-serialized event>]
+```
 
 Relays reply with an ACK message in the format of: 
 
-  * `["OK", <event_id>, <accepted>, <prefix>:<message>]`
+```js 
+["OK", <string event_id>, <bool accepted>, <string prefix:message>]
+```
 
 `OK` messages MUST be sent in response to `EVENT` messages received from clients, they must have the 3rd parameter set to `true` when an event has been accepted by the relay, `false` otherwise. The 4th parameter MUST always be present, but MAY be an empty string when the 3rd is `true`. 
 
@@ -194,7 +211,9 @@ If present, the message MUST be a string formed by a machine-readable single-wor
 
 Notices are human-readable warnings that might help explain or debug the behavior of a given relay or filter. 
 
-  * `["NOTICE", <message>]`
+```js 
+["NOTICE", <string message>]
+```
 
 ## Message Prefixes