nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-12-25 09:45:51 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

declaring types in the relay protocol messages

Browse Source
This commit is contained in:
Vitor Pamplona 2024-01-04 11:26:50 -05:00
parent 7b6a2063f3
commit a4d656a5a2
1 changed files with 36 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
01.md
View File

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