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.