provides lease extension spec

Extensions/Leasing/ConcurrencyLimitLeasing.md

@@ -0,0 +1,39 @@
+# Max Concurrency Limit Leasing Strategy Extension
+
+_This extension specification is currently incubating.  While incubating the version is 0._
+
+## Introduction
+Lease provide a powerful mechanism for `Server` to control it's stability. However, one common strategy for Leasing may not be efficient for all the cases. A common mechanism for authenticating is using a bearer token. Requests Concurrency Limit is a well-know mechanism in order to achieve optimal throughput with optimal latency. This Lease Strategy provides a standardized mechanism for negotiating Concurrency Limit using [Leasing Frame][lf].
+
+[lf]: ../../Protocol.md#frame-lease
+
+
+### Frame Contents
+```
+     0                   1                   2                   3
+     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |                         Stream ID = 0                         |
+    +-----------+-+-+---------------+-------------------------------+
+    |Frame Type |0|M|     Flags     |
+    +-----------+-+-+---------------+-------------------------------+
+    |0|                       Time-To-Live                          |
+    +---------------------------------------------------------------+
+    |0|                     Concurrency Limit                       |
+    +---------------------------------------------------------------+
+                                Metadata
+```
+
+* __Frame Type__: (6 bits) 0x02 
+* __Flags__: (10 bits)
+     * (__M__)etadata: Metadata present
+* __Time-To-Live (TTL)__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Time (in milliseconds) for validity of LEASE from time of reception. Value MUST be > 0.
+* __Concurrency Limit__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit long of Number of Max Concurrent Requests at a time. Value MUST be >= 0. 
+
+A Responder implementation MAY stop all further requests by sending a LEASE with a value of 0 for __Concurrency Limit__.
+
+When a LEASE expires due to time, the value of the __Concurrency Limit__ that a Requester may make is implicitly 0.
+
+This frame only supports Metadata, so the Metadata Length header MUST NOT be included, even if the (M)etadata flag is set true.
+
+[wk]: WellKnownLeaseStrategies.md

Extensions/Leasing/FramesCountLeasing.md

@@ -0,0 +1,38 @@
+# Frames Counting Leasing Strategy
+
+_This extension specification is currently incubating.  While incubating the version is 0._
+
+## Introduction
+Lease provides a powerful mechanism for `Server` to control its stability. However, one common strategy for Leasing may not be efficient for all cases. A common mechanism for authenticating is using a bearer token. Frame Counting is a mechanism in order to achieve stable memory consumption by controlling the number of incoming. This Lease Strategy provides a standardized negotiating mechanism allowed Frame Count using [Leasing Frame][lf].
+
+
+### Frame Contents
+
+```
+     0                   1                   2                   3
+     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |                         Stream ID = 0                         |
+    +-----------+-+-+---------------+-------------------------------+
+    |Frame Type |0|M|     Flags     |
+    +-----------+-+-+---------------+-------------------------------+
+    |0|                       Time-To-Live                          |
+    +---------------------------------------------------------------+
+    |0|                     Number of Frames                        |
+    +---------------------------------------------------------------+
+                                Metadata
+```
+
+* __Frame Type__: (6 bits) 0x02 
+* __Flags__: (10 bits)
+     * (__M__)etadata: Metadata present
+* __Time-To-Live (TTL)__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Time (in milliseconds) for validity of LEASE from time of reception. Value MUST be > 0. 
+* __Number of Frames__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Number of Frames that may be sent until next LEASE. Value MUST be >= 0. 
+
+A Responder implementation MAY stop all further frames by sending a LEASE with a value of 0 for __Number of Frames__.
+
+When a LEASE expires due to time, the value of the __Number of Frames__ that a Requester may make is implicitly 0.
+
+This frame only supports Metadata, so the Metadata Length header MUST NOT be included, even if the (M)etadata flag is set to true.
+
+[wk]: WellKnownLeaseStrategies.md

Extensions/Leasing/Leasing.md

@@ -0,0 +1,60 @@
+# Leasing Strategy Extension
+
+_This extension specification is currently incubating.  While incubating the version is 0._
+
+## Introduction
+When two systems are communicating via RSocket, it is crucial to provide a way of preserving systems stability. Even though the Leasing specification brings such an opportunity, it is not always possible to use the same leasing strategy to make communication stable.  This extension specification provides a way to specify by a `Client` using [`CompositeMedata`][cm] a set of Leasing strategies so the `Server` can choose one of them depends on the requirements and then respond as defined in the [negotiation](#negotiation) section.
+
+## Metadata Payload
+This metadata type is intended to be used per connection, and not per stream, nor individual payloads, and as such it **MUST** only be used in the [`SETUP`][sf] frame type.  The Metadata MIME Type is `message/x.rsocket.supported-lease-strategies.v0`.
+
+[sf]: ../../Protocol.md#frame-setup
+
+### Metadata Contents
+```
+     0                   1                   2                   3
+     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |L| Type ID/Len |   Lease Strategy                             ...
+    +---------------+---------------+---------------+---------------+
+    |L| Type ID/Len |   Lease Strategy                             ...
+    +---------------+---------------+---------------+---------------+
+                                   ...
+```
+
+* (**L**)Lease Strategy: Lease strategy is a well known value represented by a unique integer.  If L flag is set (a value of `1`), it indicates a [Well-known Lease Strategy ID][wk].  If L flag is not set (a value of `0`), it indicates the Lease Strategy Length in bytes.
+* **Lease Strategy ID/Length**: (7 bits = max value 2^7 = 128) Unsigned 7-bit integer.  If L flag is set (a value of `1`), it indicates a [Well-known Lease Strategy ID][wk].  If A flag is not set (a value of `0`), it indicates the Lease Strategy Length in bytes.
+* **Lease Strategy**: the strategy for leasing. This SHOULD be a US-ASCII string.  The string MUST NOT be null terminated.  (Not present if L flag is set)
+
+[wk]: WellKnownLeaseStrategies.md
+
+
+## Negotiation
+
+Once a `Client` specified [supported lease strategies](#metadata-payload), the `Server` MUST select one of the provided supported lease strategies or reject if none of the provided are supported.  In turn, to encode the selected lease strategy, `Server` MUST use the metadata field of the `LEASE`:
+
+### Metadata Contents
+```
+     0                   1                   2                   3
+     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |L| Type ID/Len |   Lease Strategy                                  
+    +---------------+---------------+---------------+---------------+
+```
+
+* (**L**)Lease Strategy: Lease strategy is a well known value represented by a unique integer.  If L flag is set (a value of `1`), it indicates a [Well-known Strategy Type ID][wk].  If L flag is not set (a value of `0`), it indicates the Lease Strategy Length in bytes.
+* **Lease Strategy ID/Length**: (7 bits = max value 2^7 = 128) Unsigned 7-bit integer.  If L flag is set (a value of `1`), it indicates a [Well-known Strategy Type ID][wk].  If A flag is not set (a value of `0`), it indicates the Lease Strategy Length in bytes.
+* **Lease Strategy**: the strategy for leasing. This SHOULD be a US-ASCII string.  The string MUST NOT be null terminated.  (Not present if L flag is set)
+
+[wk]: WellKnownLeaseStrategies.md
+
+Note, if the selected lease strategy has a different frame layout than the default one, the first [`LEASE`][lf] frame MUST follow the default [`LEASE`][lf] frame layout to let the `Client` read metadata field content 
+
+
+[lf]: ../../Protocol.md#frame-lease
+
+### Handling Unexpected
+
+If `Server` does not specify lease strategy defined in the [negotiation](#negotiation) section, the `Client` MUST close the connection with the __CONNECTION_ERROR__ [Error Code][ec] and reestablishe connection without specifying lease strategies or without leasing at all.
+
+[ec]: ../../Protocol.md#error-codes

Extensions/Leasing/WellKnownLeaseStrategies.md

@@ -0,0 +1,20 @@
+# Well-known Lease Strategies
+
+## Introduction
+The [Lease Strategy Extension][le] provides a standardized mechanism for negotiating Lease Strategy in the [Setup Frame][sf] metadata payload. Lease Strategies define how to read the Lease Strategies Metadata Payload. However, due to their definitions as strings and the number of times they need to be sent as part of typical interaction, they can be wasteful in their typical form.  Because of this, it's useful to represent well-known Lease Strategies as integer values during transmission.  This behavior does not remove the need or ability in the specifications to declare Lease Strategies as strings.
+
+[le]: Leasing.md
+[sf]: ../../Protocol.md#frame-setup
+
+## Mappings
+All well-known Lease Strategies assume UTF-8 character encoding wherever a character set might be necessary.  If another character set is required, a string-based Lease Type should be used.
+
+| Lease Strategy                             | Identifier
+| -------------------------------------------| ----------
+| [`Requests Count`][request-leasing]        | `0x00`
+| [`Concurrency Limit`][concurrency-leasing] | `0x01`
+| [`Frames Count`][frames-leasing]           | `0x02`
+
+[request-leasing]: ../../Protocol.md#frame-lease
+[concurrency-leasing]: ConcurrencyLimitLeasing.md
+[frames-leasing]: FramesCountLeasing.md

Extensions/WellKnownMimeTypes.md

@@ -50,6 +50,7 @@ All well-known MIME types assume UTF-8 character encoding wherever a character s
 | `application/x-java-object` | `0x27`
 | `application/cloudevents+json` | `0x28`
 | |
+| `message/x.rsocket.supported-lease-strategies.v0` | `0x79`
 | `message/x.rsocket.mime-type.v0` | `0x7A`
 | `message/x.rsocket.accept-mime-types.v0` | `0x7b`
 | `message/x.rsocket.authentication.v0` | `0x7C`

Protocol.md

@@ -412,6 +412,8 @@ The last received LEASE frame overrides all previous LEASE frame values.
 
 Lease frames MUST always use Stream ID 0 as they pertain to the Connection.
 
+Note, Lease Frame layout depends on the lease strategy specified by [Lease Strategies Extension spec](./Extensions/Leasing/Leasing.md)
+
 Frame Contents
 
 ```
@@ -433,9 +435,9 @@ Frame Contents
 * __Flags__: (10 bits)
      * (__M__)etadata: Metadata present
 * __Time-To-Live (TTL)__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Time (in milliseconds) for validity of LEASE from time of reception. Value MUST be > 0. 
-* __Number of Requests__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Number of Requests that may be sent until next LEASE. Value MUST be > 0. 
+* __Number of Requests__: (31 bits = max value 2^31-1 = 2,147,483,647) Unsigned 31-bit integer of Number of Requests that may be sent until next LEASE. Value MUST be >= 0. 
 
-A Responder implementation MAY stop all further requests by sending a LEASE with a value of 0 for __Number of Requests__ or __Time-To-Live__.
+A Responder implementation MAY stop all further requests by sending a LEASE with a value of 0 for __Number of Requests__.
 
 When a LEASE expires due to time, the value of the __Number of Requests__ that a Requester may make is implicitly 0.