From 01926e3da2baaf5bb519658473944283da812bd7 Mon Sep 17 00:00:00 2001 From: Semisol <45574030+Semisol@users.noreply.github.com> Date: Fri, 3 Jan 2025 10:38:04 +0300 Subject: [PATCH 1/3] Create NIP-91 --- 91.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 91.md diff --git a/91.md b/91.md new file mode 100644 index 00000000..f18ef157 --- /dev/null +++ b/91.md @@ -0,0 +1,87 @@ +NIP-91 +====== + +Protocol Negotiation +-------------------- + +`draft` `optional` + +This NIP defines a method for clients to negotiate extension protocols with relays. + +## Protocol Names + +Each protocol has a **protocol name** that can uniquely identify the protocol. Currently the following formats are recommended: +- `nip-XX-`: For protocols standardized in NIPs. Experimental protocols are recommended to have a unique description to not conflict. +- `/`: For custom protocols. The namespace should uniquely identify the standardizing body for this protocol with a DNS name. (example: `example.com/example-protocol`) +- `x/`: For custom protocols without a namespace. + +Any protocol name outside this list MUST NOT be used. + +## Protocol Offers + +The relay may send a protocol offer as a `PN-OFFER` message: +```jsonc +[ + "PN-OFFER", + { + "example.com/example-protocol": {...}, + "nip-XX-example-protocol": {...} + } +] +``` + +The 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. + +A 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. + +Clients SHOULD be able to handle protocol offers being able to be withdrawn. The removal of a protocol from a `PN-OFFER` does not affect existing active protocols, a `PN-SHUTDOWN` must be sent if that is required. + +## Protocol Requests + +A client may request a protocol offered by the relay be enabled with the `PN-REQUEST` message: +```jsonc +[ + "PN-REQUEST", + "example.com/example-protocol", + {...} +] +``` + +The first entry MUST be the protocol name, and the second entry MUST be a protocol-dependent object for the protocol enable request. + +The relay SHOULD respond with a `PN-OK` or `PN-ERROR` message: +```jsonc +[ + "PN-OK", + "example.com/example-protocol", + {...} +] +``` +```jsonc +[ + "PN-ERROR", + "example.com/example-protocol", + "improper protocol request data" +] +``` + +In both messages, the first entry MUST be the protocol name. The second entry depends on the type: +- `PN-OK`: Response data for the protocol negotiation. After this message, the protocol can be used. +- `PN-ERROR`: An error message. + +An 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: +- `error`: An internal error has occurred in the relay. +- `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`. +- `bad-data`: The client has sent improper protocol negotiation data. + +## Protocol Shutdown + +The relay or client may shut down the usage of the protocol any time with a `PN-SHUTDOWN` message: +```jsonc +[ + "PN-SHUTDOWN", + "example.com/example-protocol" +] +``` + +After 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. From 8231c8e1e91d851df70d793c0f36ab730c33b506 Mon Sep 17 00:00:00 2001 From: Semisol <45574030+Semisol@users.noreply.github.com> Date: Fri, 3 Jan 2025 10:41:40 +0300 Subject: [PATCH 2/3] Update NIP-91 --- 91.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/91.md b/91.md index f18ef157..90292168 100644 --- a/91.md +++ b/91.md @@ -34,7 +34,9 @@ The first entry MUST be an object, with the keys being protocol names, and the v A 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. -Clients SHOULD be able to handle protocol offers being able to be withdrawn. The removal of a protocol from a `PN-OFFER` does not affect existing active protocols, a `PN-SHUTDOWN` must be sent if that is required. +Clients 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. + +Certain protocols, such as extensions to REQs, may not need negotiation. This is up to the specification of the specific protocol. ## Protocol Requests From fc323706fab84cb5e55a54ca8286f8e76794ac83 Mon Sep 17 00:00:00 2001 From: Semisol <45574030+Semisol@users.noreply.github.com> Date: Fri, 3 Jan 2025 15:29:20 +0300 Subject: [PATCH 3/3] Update NIP-91 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. --- 91.md | 77 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/91.md b/91.md index 90292168..1cf3197d 100644 --- a/91.md +++ b/91.md @@ -1,89 +1,88 @@ NIP-91 ====== -Protocol Negotiation --------------------- +Extension Negotiation +--------------------- `draft` `optional` -This NIP defines a method for clients to negotiate extension protocols with relays. +This NIP defines a method for clients to negotiate new features with relays. -## Protocol Names +## Extension Names -Each protocol has a **protocol name** that can uniquely identify the protocol. Currently the following formats are recommended: -- `nip-XX-`: For protocols standardized in NIPs. Experimental protocols are recommended to have a unique description to not conflict. -- `/`: For custom protocols. The namespace should uniquely identify the standardizing body for this protocol with a DNS name. (example: `example.com/example-protocol`) -- `x/`: For custom protocols without a namespace. +Each extension has a **extension name** that can uniquely identify the extension. Currently the following formats are recommended: +- `nip/XX-`: For extensions that are standardized in NIPs. Experimental extensions are recommended to have a unique description to not conflict. +- `/`: 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`) -Any protocol name outside this list MUST NOT be used. +Any extension name outside this list MUST NOT be used. -## Protocol Offers +## Extension Offers -The relay may send a protocol offer as a `PN-OFFER` message: +The 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`. ```jsonc [ - "PN-OFFER", + "EN-OFFER", { - "example.com/example-protocol": {...}, - "nip-XX-example-protocol": {...} + "example.com/example-extension": {...}, + "nip-XX-example-extension": {...} } ] ``` -The 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. +The 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. -A 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. +A 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. -Clients 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. +Clients 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. -Certain protocols, such as extensions to REQs, may not need negotiation. This is up to the specification of the specific protocol. +Certain extensions, such as extensions to REQs, may not need negotiation. This is up to the extension specification. -## Protocol Requests +## Extension Requests -A client may request a protocol offered by the relay be enabled with the `PN-REQUEST` message: +A client may request a extension offered by the relay be enabled with the `EN-REQUEST` message: ```jsonc [ - "PN-REQUEST", - "example.com/example-protocol", + "EN-REQUEST", + "example.com/example-extension", {...} ] ``` -The first entry MUST be the protocol name, and the second entry MUST be a protocol-dependent object for the protocol enable request. +The first entry MUST be the extension name, and the second entry MUST be a extension-dependent object for the extension enable request. -The relay SHOULD respond with a `PN-OK` or `PN-ERROR` message: +The relay SHOULD respond with a `EN-OK` or `EN-ERROR` message: ```jsonc [ - "PN-OK", - "example.com/example-protocol", + "EN-OK", + "example.com/example-extension", {...} ] ``` ```jsonc [ - "PN-ERROR", - "example.com/example-protocol", - "improper protocol request data" + "EN-ERROR", + "example.com/example-extension", + "improper extension request data" ] ``` -In both messages, the first entry MUST be the protocol name. The second entry depends on the type: -- `PN-OK`: Response data for the protocol negotiation. After this message, the protocol can be used. -- `PN-ERROR`: An error message. +In both messages, the first entry MUST be the extension name. The second entry depends on the type: +- `EN-OK`: Response data for the extension negotiation. After this message, the extension can be used. +- `EN-ERROR`: An error message. An 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: - `error`: An internal error has occurred in the relay. -- `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`. -- `bad-data`: The client has sent improper protocol negotiation data. +- `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`. +- `bad-data`: The client has sent improper extension negotiation data. -## Protocol Shutdown +## Extension Cancel -The relay or client may shut down the usage of the protocol any time with a `PN-SHUTDOWN` message: +The relay or client may stop the usage of the extension any time with a `EN-CANCEL` message: ```jsonc [ - "PN-SHUTDOWN", - "example.com/example-protocol" + "EN-CANCEL", + "example.com/example-extension" ] ``` -After 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. +After 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.