upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSemisol <45574030+Semisol@users.noreply.github.com>2025-01-03 15:29:20 +0300
committerGitHub <noreply@github.com>2025-01-03 15:29:20 +0300
commitfc323706fab84cb5e55a54ca8286f8e76794ac83 (patch)
tree3659670bdfbd9fb7dde804ee9aeb1a3cc305f2f0
parent8231c8e1e91d851df70d793c0f36ab730c33b506 (diff)
Update NIP-91nip91
The NIP has been renamed to represent the goals of the NIP more accurately. The x/ extension namespace has been removed, and any features meant to be standardized as a NIP should create a preliminary PR and use the `nip/` namespace. Any extensions that are meant to be standardized externally should use their own namespace.
-rw-r--r--91.md77
1 files changed, 38 insertions, 39 deletions
diff --git a/91.md b/91.md
index 9029216..1cf3197 100644
--- a/91.md
+++ b/91.md
@@ -1,89 +1,88 @@
1NIP-91 1NIP-91
2====== 2======
3 3
4Protocol Negotiation 4Extension Negotiation
5-------------------- 5---------------------
6 6
7`draft` `optional` 7`draft` `optional`
8 8
9This NIP defines a method for clients to negotiate extension protocols with relays. 9This NIP defines a method for clients to negotiate new features with relays.
10 10
11## Protocol Names 11## Extension Names
12 12
13Each protocol has a **protocol name** that can uniquely identify the protocol. Currently the following formats are recommended: 13Each extension has a **extension name** that can uniquely identify the extension. Currently the following formats are recommended:
14- `nip-XX-<description>`: For protocols standardized in NIPs. Experimental protocols are recommended to have a unique description to not conflict. 14- `nip/XX-<description>`: For extensions that are standardized in NIPs. Experimental extensions are recommended to have a unique description to not conflict.
15- `<namespace>/<protocol>`: For custom protocols. The namespace should uniquely identify the standardizing body for this protocol with a DNS name. (example: `example.com/example-protocol`) 15- `<namespace>/<extension>`: For extensions standardized by an independent body. The namespace should uniquely identify the standardizing body for this extension with a DNS name. (example: `example.com/example-extension`)
16- `x/<protocol>`: For custom protocols without a namespace.
17 16
18Any protocol name outside this list MUST NOT be used. 17Any extension name outside this list MUST NOT be used.
19 18
20## Protocol Offers 19## Extension Offers
21 20
22The relay may send a protocol offer as a `PN-OFFER` message: 21The relay may send a extension offer as a `EN-OFFER` message. The client SHOULD NOT send any messages relating to extension negotiation until it receives an `EN-OFFER`.
23```jsonc 22```jsonc
24[ 23[
25 "PN-OFFER", 24 "EN-OFFER",
26 { 25 {
27 "example.com/example-protocol": {...}, 26 "example.com/example-extension": {...},
28 "nip-XX-example-protocol": {...} 27 "nip-XX-example-extension": {...}
29 } 28 }
30] 29]
31``` 30```
32 31
33The first entry MUST be an object, with the keys being protocol names, and the values being objects. The format of the object is up to the protocol to define. 32The first entry MUST be an object, with the keys being extension names, and the values being objects. The format of the object is left to the specification of the specific extension.
34 33
35A protocol offer can be sent multiple times in a connection, such as to update availability based off of their [NIP-42](./42.md) authentication status. 34A extension offer can be sent multiple times in a connection, such as to update availability based off of their [NIP-42](./42.md) authentication status.
36 35
37Clients SHOULD be able to handle protocol offers being able to be withdrawn, and should treat them as if it was a `PN-SHUTDOWN` if they were in use. 36Clients SHOULD be able to handle extension offers being able to be withdrawn, and should treat them as if it was a `EN-SHUTDOWN` if they were in use.
38 37
39Certain protocols, such as extensions to REQs, may not need negotiation. This is up to the specification of the specific protocol. 38Certain extensions, such as extensions to REQs, may not need negotiation. This is up to the extension specification.
40 39
41## Protocol Requests 40## Extension Requests
42 41
43A client may request a protocol offered by the relay be enabled with the `PN-REQUEST` message: 42A client may request a extension offered by the relay be enabled with the `EN-REQUEST` message:
44```jsonc 43```jsonc
45[ 44[
46 "PN-REQUEST", 45 "EN-REQUEST",
47 "example.com/example-protocol", 46 "example.com/example-extension",
48 {...} 47 {...}
49] 48]
50``` 49```
51 50
52The first entry MUST be the protocol name, and the second entry MUST be a protocol-dependent object for the protocol enable request. 51The first entry MUST be the extension name, and the second entry MUST be a extension-dependent object for the extension enable request.
53 52
54The relay SHOULD respond with a `PN-OK` or `PN-ERROR` message: 53The relay SHOULD respond with a `EN-OK` or `EN-ERROR` message:
55```jsonc 54```jsonc
56[ 55[
57 "PN-OK", 56 "EN-OK",
58 "example.com/example-protocol", 57 "example.com/example-extension",
59 {...} 58 {...}
60] 59]
61``` 60```
62```jsonc 61```jsonc
63[ 62[
64 "PN-ERROR", 63 "EN-ERROR",
65 "example.com/example-protocol", 64 "example.com/example-extension",
66 "improper protocol request data" 65 "improper extension request data"
67] 66]
68``` 67```
69 68
70In both messages, the first entry MUST be the protocol name. The second entry depends on the type: 69In both messages, the first entry MUST be the extension name. The second entry depends on the type:
71- `PN-OK`: Response data for the protocol negotiation. After this message, the protocol can be used. 70- `EN-OK`: Response data for the extension negotiation. After this message, the extension can be used.
72- `PN-ERROR`: An error message. 71- `EN-ERROR`: An error message.
73 72
74An error message SHOULD start with a single-word prefix, followed by a colon (:) and space character, and a human readable message. The following types are defined: 73An error message SHOULD start with a single-word prefix, followed by a colon (:) and space character, and a human readable message. The following types are defined:
75- `error`: An internal error has occurred in the relay. 74- `error`: An internal error has occurred in the relay.
76- `not-offered`: The protocol was not offered. This may happen due to a `PN-REQUEST` being sent at the same time as a new `PN-OFFER`. 75- `not-offered`: The extension was not offered. This may happen due to a `EN-REQUEST` being sent at the same time as a new `EN-OFFER`.
77- `bad-data`: The client has sent improper protocol negotiation data. 76- `bad-data`: The client has sent improper extension negotiation data.
78 77
79## Protocol Shutdown 78## Extension Cancel
80 79
81The relay or client may shut down the usage of the protocol any time with a `PN-SHUTDOWN` message: 80The relay or client may stop the usage of the extension any time with a `EN-CANCEL` message:
82```jsonc 81```jsonc
83[ 82[
84 "PN-SHUTDOWN", 83 "EN-CANCEL",
85 "example.com/example-protocol" 84 "example.com/example-extension"
86] 85]
87``` 86```
88 87
89After this message, the sending party will no longer accept and send new protocol messages, and the receiver should not continue attempting to use the protocol functionality. 88After this message, the sending party will no longer accept and send new extension messages, and the receiver should not continue attempting to use the extension functionality.