From 6f99082a0013f02fd01faf2c844d41ac437bc867 Mon Sep 17 00:00:00 2001 From: Gabriele Vernetti Date: Mon, 25 Nov 2024 17:24:15 +0100 Subject: [PATCH 1/2] extensions-negotiation definition --- 03-Protocol-Overview.md | 4 + 09-Extensions.md | 6 +- extensions/extensions-negotiation.md | 105 +++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 extensions/extensions-negotiation.md diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index 3b0d84b..51149f6 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -126,6 +126,10 @@ If a device is aware of the semantics of a given extension type, it MUST process Messages with an unknown `extension_type` which are to be processed locally (as defined above) MUST be discarded and ignored. +### 3.4.1 Implementing Extensions Support + +To support extensions, an implementation MUST first implement **Extension 1**, which defines the basic protocol for requesting and negotiating support for extensions. This extension must be included in any protocol implementation that plans to support additional protocol extensions. + Extensions MUST require version negotiation with the recipient of the message to check that the extension is supported before sending non-version-negotiation messages for it. This prevents the needlessly wasted bandwidth and potentially serious performance degradation of extension messages when the recipient does not support them. diff --git a/09-Extensions.md b/09-Extensions.md index 3f0abbf..4188c7a 100644 --- a/09-Extensions.md +++ b/09-Extensions.md @@ -1,6 +1,6 @@ # 9. Extensions There are not yet any defined extensions. -| Extenstion Type | Extension Name | Description / BIP | -| -------------------- | -------------- | ---------------------------------------------------------------------------- | -| (no channel_msg bit) | | | +| Extension Type | Extension Name | Description / BIP | +| -------------- | ---------------------- | --------------------------------------------------------- | +| 0x0001 | Extensions Negotiation | Definition [here](./extensions/extensions-negotiation.md) | diff --git a/extensions/extensions-negotiation.md b/extensions/extensions-negotiation.md new file mode 100644 index 0000000..5d61878 --- /dev/null +++ b/extensions/extensions-negotiation.md @@ -0,0 +1,105 @@ +# Stratum V2 Extension: Extensions Negotiation + +## 0. Abstract + +This document defines a Stratum V2 extension to negotiate support for other protocol extensions between clients and servers. + +The mechanism allows clients to request support for a list of extensions immediately after the `SetupConnection` message exchange. The server responds with either: +- `RequestExtensions.Success`, listing the supported extensions. +- `RequestExtensions.Error`, listing the unsupported extensions. + +This negotiation ensures that both parties can establish a common set of features before exchanging further protocol messages. + +Terms like "MUST," "MUST NOT," "REQUIRED," etc., follow RFC2119 standards. + +--- + +## 1. Overview + +### 1.1 Negotiating Extensions + +After the successful `SetupConnection` exchange, clients MUST send a `RequestExtensions` message to indicate the extensions they wish to use. The server responds with: +- `RequestExtensions.Success`, confirming which extensions are supported. +- `RequestExtensions.Error`, identifying unsupported extensions. + +Clients MUST NOT use any features from extensions that are not confirmed as supported by the server. + +#### Message Exchange Example + +1. **Connection Setup**: + ``` + Client --- SetupConnection (connection details) ---> Server + Client <--- SetupConnection.Success (connection accepted) ---- Server + ``` + +2. **Extension Negotiation**: + ``` + Client --- RequestExtensions (list of requested U16) ---> Server + ``` + +3. **Server Response**: + - If successful: + ``` + Client <--- RequestExtensions.Success (list of supported U16) ---- Server + ``` + - If an error occurs: + ``` + Client <--- RequestExtensions.Error (list of unsupported U16) ---- Server + ``` + +--- + +## 2. Messages Defined by This Extension + +### `RequestExtensions` (Client -> Server) + +| Field Name | Data Type | Description | +|----------------------|--------------|-----------------------------------------------| +| request_id | U16 | Unique identifier for pairing the response. | +| requested_extensions | SEQ0_64K[U16]| List of requested extension identifiers. | + +### `RequestExtensions.Success` (Server -> Client) + +| Field Name | Data Type | Description | +|----------------------|--------------|-----------------------------------------------| +| request_id | U16 | Unique identifier for pairing the response. | +| supported_extensions | SEQ0_64K[U16]| List of supported extension identifiers. | + +### `RequestExtensions.Error` (Server -> Client) + +| Field Name | Data Type | Description | +|------------------------|--------------|-----------------------------------------------| +| request_id | U16 | Unique identifier for pairing the response. | +| unsupported_extensions | SEQ0_64K[U16]| List of unsupported extension identifiers. | + +--- + +## 3. Message Types + +| Message Type (8-bit) | channel_msg_bit | Message Name | +|----------------------|-----------------|---------------------------| +| 0x00 | 0 | RequestExtensions | +| 0x01 | 0 | RequestExtensions.Success | +| 0x02 | 0 | RequestExtensions.Error | + +--- + +## 4. Implementation Notes + +1. **Error Handling**: + - Servers MUST respond with `RequestExtensions.Error` if none of the requested extensions are supported. + - Servers MAY include an empty `unsupported_extensions` field in the error message if no extensions are explicitly unsupported. + +2. **Ordering**: + - The `RequestExtensions` message MUST be sent immediately after `SetupConnection.Success` and before any other protocol-specific messages. + +3. **Backward Compatibility**: + - Servers that do not support this extension will ignore the `RequestExtensions` message, leading to a connection timeout. + +4. **Example Use Case**: + A client requesting support for extensions `0x0002` and `0x0003`: + ``` + Client --- RequestExtensions [0x0002, 0x0003] ---> Server + Client <--- RequestExtensions.Success [0x0002] ---- Server + ``` + The client now knows that extension `0x0003` is not supported and must adapt its behavior accordingly. From 64bb6253a8a57d960fd1b9e06eedb58cdd2d1fea Mon Sep 17 00:00:00 2001 From: GitGab19 Date: Tue, 10 Dec 2024 12:16:07 +0700 Subject: [PATCH 2/2] backward compatibility clarifications --- extensions/extensions-negotiation.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/extensions/extensions-negotiation.md b/extensions/extensions-negotiation.md index 5d61878..8289707 100644 --- a/extensions/extensions-negotiation.md +++ b/extensions/extensions-negotiation.md @@ -93,8 +93,15 @@ Clients MUST NOT use any features from extensions that are not confirmed as supp 2. **Ordering**: - The `RequestExtensions` message MUST be sent immediately after `SetupConnection.Success` and before any other protocol-specific messages. -3. **Backward Compatibility**: - - Servers that do not support this extension will ignore the `RequestExtensions` message, leading to a connection timeout. +#### 3. **Backward Compatibility**: +- **Server Behavior**: + - Servers that do not support this extension will ignore the `RequestExtensions` message, potentially leading to a connection timeout. + +- **Client Behavior**: + - Clients MUST NOT send any further protocol-specific messages until they receive a `RequestExtensions.Success` or `RequestExtensions.Error` response. + - If the client does not receive a response within a reasonable timeout period (e.g., X seconds, where X is implementation-defined), it SHOULD close the connection and report the timeout as an error. + +This ensures clients can handle servers that do not implement extensions negotiation gracefully while avoiding indefinite blocking. 4. **Example Use Case**: A client requesting support for extensions `0x0002` and `0x0003`: