Skip to content

Latest commit

 

History

History
778 lines (595 loc) · 34.2 KB

Protocol.md

File metadata and controls

778 lines (595 loc) · 34.2 KB
Raw

Introduction

Key words used by this document conform to the meanings in RFC 2119.

Terminology

  • Frame: A frame of data containing a request or a response.
  • Transport: Protocol used to carry ReactiveSockets protocol. Such as WebSockets, TCP, Aeron, etc. The transport is assumed to provide reliable delivery.
  • Stream: Unit of operation (request/response, etc.). See Design Principles.
  • Request: A stream request. May be one of four types. As well as request for more items or cancellation of previous request.
  • Response: A stream response. Contains data associated with previous request.
  • Client: The side initiating a connection.
  • Server: The side accepting connections from clients.
  • Connection: The instance of a transport session between client and server.
  • Requester: The side sending a request. A connection has at most 2 Requesters. One in each direction.
  • Responder: The side receiving a request. A connection has at most 2 Responders. One in each direction.

Data And Metadata

ReactiveSocket provides mechanisms for applications to distinguish payload into two types. Data and Metadata. The distinction between the types in an application is left to the application.

The following are features of Data and Metadata.

  • Metadata can be encoded differently than Data.
  • Metadata can be "attached" (i.e. correlated) with the following entities:
    • Connection via Metadata Push and Stream ID of 0
    • Stream via Metadata Push and Stream ID of non-0
    • Individual Response via Metadata header

Operation

Frame Header Format

ReactiveSocket frames begin with a header. The general layout is given below. When used over transport protocols that provide framing (WebSocket and Aeron), the Frame Length field is not included. For transports that do not provide framing, such as TCP, the Frame Length MUST be included.

     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |I|M|  Flags    |         Frame Type            |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                           Depends on Frame Type
  • Frame Length: (31 = max 2,147,483,647 bytes) Length of Frame. Including header. Only used for TCP. The R bit is reserved.
  • Version: (8) Current version is 0.
  • Flags: Any Flag bit not specifically indicated in the frame type should be set to 0 when sent and not interpreted on reception.
    • (I)gnore: Ignore frame if not understood
    • (M)etadata: Metadata present
  • Frame Type: (16) Type of Frame.
  • Stream ID: (64) Stream Identifier for this frame.

Metadata Optional Header

Specific Frame Types MAY contain an optional metadata header that provides metadata about a frame. This metadata header is between the Frame Header and any payload.

Metadata Length MUST be less than or equal to the Frame Length minus the length of the Frame Header. If Metadata Length is greater than this value, the entire frame MUST be ignored.

     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |       Type    |           Metadata Length                     |
    +---------------+-----------------------------------------------+
    |                       Metadata Payload                       ...
    +---------------------------------------------------------------+
    |                       Payload of Frame                       ...
    +---------------------------------------------------------------+
  • Type: Application-defined Type field for the metadata. Not interpretted by protocol.
  • Metadata Length: (24 = max 16,777,216 bytes) Length of Metadata. Including Metadata header.

Stream Identifiers

Generation

Stream IDs are generated by a Requester. The lifetime of a Stream ID is determined by the request type and the semantics of the stream based on its type.

Stream ID value of 0 is reserved for any operation involving the connection.

A stream ID must be locally unique for a Requester in a connection.

Frame Types

Type Value Description
RESERVED 0x0000 Reserved
SETUP 0x0001 Setup: Capabilities Of Side Sending The Frame.
SETUP_ERROR 0x0002 Setup Error: Error from SETUP.
LEASE 0x0003 Lease:
KEEPALIVE 0x0004 Keepalive: Connection keepalive.
REQUEST_RESPONSE 0x0011 Request Response:
REQUEST_FNF 0x0012 Fire And Forget:
REQUEST_STREAM 0x0013 Request Stream:
REQUEST_SUB 0x0014 Request Subscription:
REQUEST_N 0x0015 Request N: Request N more items
CANCEL 0x0016 Cancel Request:
RESPONSE 0x0020 Response: Response to a request.
ERROR 0x0021 Error: Response that is an error.
METADATA_PUSH 0x0031 Metadata: Asynchronous Metadata frame
EXT 0xFFFF Extension Header: Used To Extend More Options As Well As Extensions.

NOTE: In general Requesters send types 0x0010 to 0x001F and Responders send types 0x0020 to 0x002F. Types 0x0001 to 0x000F pertain to the entire connection. Types 0x0030 to 0x003F pertain to all levels depending on context.

Setup Frame

Setup frames MUST always use Stream ID 0 as they pertain to the connection.

The encoding format for Data and Metadata are included separately in the SETUP.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-+-+-------+-------------------------------+
    |    Version    |0|M|L|S| Flags |     Frame Type = SETUP        |
    +---------------+-+-+-+-+-------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                   Time Between KEEPALIVE Frames               |
    +---------------------------------------------------------------+
    |                         Max Lifetime                          |
    +---------------+-----------------------------------------------+
    |  MIME Length  |   Metadata Encoding MIME Type                ...
    +---------------+-----------------------------------------------+
    |  MIME Length  |     Data Encoding MIME Type                  ...
    +---------------+-----------------------------------------------+
                          Metadata & Setup Payload
  • Flags:
    • (M)etadata: Metdadata present
    • (L): Will honor LEASE (or not).
    • (S)trict: Adhere to strict interpretation of Data and Metadata.
  • Time Between KEEPALIVE Frames: Time (in nanoseconds) between KEEPALIVE frames that the client will send.
  • __Max Lifetime __: Time (in nanoseconds) that a client will allow a server to not respond to a KEEPALIVE before it is assumed to be dead.
  • MIME Length: Encoding MIME Type Length in bytes.
  • Encoding MIME Type: MIME Type for encoding of Data and Metadata. This is a US-ASCII string that includes the Internet media type specified in RFC 2045. Many are registered with IANA such as CBOR
  • Setup Data: includes payload describing connection capabilities of the endpoint sending the Setup header.

NOTE: Suffix rules SHOULD be used for handling layout. For example, application/x.netflix+cbor or application/x.reactivesocket+cbor or application/x.netflix+json.

Setup Error Frame

Setup Error frames MUST always use Stream ID 0 as they pertain to the connection.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |     Frame Type = SETUP_ERROR  |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                          Error Code                           |
    +---------------------------------------------------------------+
                        Metadata & Setup Error Data
  • Flags:
    • (M)etadata: Metdadata present
  • Error Code: Type of Error.
  • Setup Error Data: includes payload describing connection capabilities of the endpoint sending the Setup header. Error Data MUST be a UTF-8 encoded string.

Error Codes

Type Value Description
RESERVED 0x0000 Reserved
INVALID_SETUP 0x0001 The Setup frame is invalid for the server (it could be that the client is too recent for the old server)
UNSUPPORTED_SETUP 0x0010 Some (or all) of the parameters specified by the client are unsupported by the server
REJECTED_SETUP 0x0100 The server rejected the setup, it can specify the reason in the payload
RESERVED 0xFFFF Reserved for Extension Use

Lease Frame

Lease frames MUST always use Stream ID 0 as they pertain to the Connection.

Lease frames MAY be sent by the client-side or server-side Responders and inform the Requester that it may send Requests for a period of time and how many it may send.

The last received LEASE frame overrides all previous LEASE frame values.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |     Frame Type = LEASE        |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                         Time-To-Live                          |
    |                                                               |
    +---------------------------------------------------------------+
    |                       Number of Requests                      |
    |                                                               |
    +---------------------------------------------------------------+
                                Metadata
  • Flags:
    • (M)etadata: Metdadata present
  • Time-To-Live (TTL): Time (in nanoseconds) for validity of LEASE from time of reception
  • Number of Requests: Number of Requests that may be sent until next LEASE

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.

Keepalive Frame

KEEPALIVE frames MUST always use Stream ID 0 as they pertain to the Connection.

KEEPALIVE frames MUST be initiated by the client and sent periodically.

Reception of a KEEPALIVE frame on a server indicates the client is alive. A server MUST send a KEEPALIVE frame back to the client upon reception of a KEEPALIVE.

A client may add data to a KEEPALIVE frame that is echoed back on the KEEPALIVE frame to the client.

A reasonable time interval between KEEPALIVE frames SHOULD be 500ms.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|0|  Flags    |     Frame Type = KEEPALIVE    |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                                  Data
  • Flags:
    • (M)etadata: Metdadata never present
  • Data: Data attached to a KEEPALIVE from the client and echoed back by the server.

Request Response Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    | Frame Type = REQUEST_RESPONSE |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                         Metadata & Request Data
  • Flags:
    • (M)etadata: Metdadata present
  • Request Data: identification of the service being requested along with parameters for the request.

Request Fire-n-Forget Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |    Frame Type = REQUEST_FNF   |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                          Metadata & Request Data
  • Flags:
    • (M)etadata: Metdadata present
  • Request Data: identification of the service being requested along with parameters for the request.

Request Stream Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |  Frame Type = REQUEST_STREAM  |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                        Initial Request N                      |
    |                                                               |
    +---------------------------------------------------------------+
                          Metadata & Request Data
  • Flags:
    • (M)etadata: Metdadata present
  • Initial Request N: initial Request N value. 64-bit integer.
  • Request Data: identification of the service being requested along with parameters for the request.

Request Subscription Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |    Frame Type = REQUEST_SUB   |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                       Initial Request N                       |
    |                                                               |
    +---------------------------------------------------------------+
                           Metadata & Request Data
  • Flags:
    • (M)etadata: Metdadata present
  • Initial Request N: initial Request N value. 64-bit integer.
  • Request Data: identification of the service being requested along with parameters for the request.

Request N Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|   Flags   |     Frame Type = REQUEST_N    |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
    |                           Request N                           |
    |                                                               |
    +---------------------------------------------------------------+
                                Metadata
  • Flags:
    • (M)etadata: Metdadata present
  • Request N: 64-bit integer value of items to request.

Cancel Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M|  Flags    |     Frame Type = CANCEL       |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                                Metadata
  • Flags:
    • (M)etadata: Metdadata present

Response Frame

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-+-+-------+-------------------------------+
    |    Version    |0|M|F|C|       |    Frame Type = RESPONSE      |
    +---------------+-+-+-+-+-------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                         Metadata & Response Data
  • Flags:
    • (M)etadata: Metadata Present.
    • (F)ollows: More fragments follow this fragment.
    • (C)omplete: bit to indicate COMPLETE.
  • Response Data: payload for onNext.

A Response is generally referred to as a NEXT.

A Response with the Complete Bit set is referred to as a COMPLETE.

Error Frame

An ERROR frame is used as a means of communicating a stream ERROR from a Responder to a Requester.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|M| Reserved  |      Frame Type = ERROR       |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                           Metadata & Error Data
  • Flags:
    • (M)etadata: Metdadata present
  • Error Data: error information. Error Data MUST be a UTF-8 encoded string.

Metadata Push Frame

A Metadata Push frame can be used to send asynchronous metadata notifications from a Requester or Responder to its peer. Metadata MUST be scoped to the connection by setting Stream ID to 0.

Metadata tied to a particular Request, Response, etc. uses the individual frames Metadata flag.

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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |0|1| Reserved  |   Frame Type = METADATA_PUSH  |
    +---------------+-+-+-----------+-------------------------------+
    |                           Stream ID                           |
    |                                                               |
    +---------------------------------------------------------------+
                                Metadata
  • Flags:
    • (M)etadata: Metdadata always present
  • Stream ID: May be 0 to pertain to the entire connection or non-0 value to pertain to just that Stream.

Extension Frame

The general format for an extension frame is given below.

     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |R|                 Frame Length (for TCP only)                 |
    +---------------+-+-+-----------+-------------------------------+
    |    Version    |I|M|  Flags    |     Frame Type = EXT          |
    +---------------+-+-+-----------+-------------------------------+
    |                        Extended Type                          |
    +---------------------------------------------------------------+
                          Depends on Extended Type...
  • Frame Type: (16) 0xFFFF for Extension Header.
  • Flags:
    • (I)gnore: Can be frame be ignored if not understood?
    • (M)etadata: Metadata Present.
  • Extended Type: Extended type information

Connection Establishment

NOTE: The semantics are similar to TLS False Start.

Immediately upon successful connection, the client MUST send a SETUP frame with Stream ID of 0. Any other frame received that is NOT a SETUP frame or a SETUP frame with a non-0 Stream ID, MUST cause the server to send a SETUP_ERROR (with INVALID_SETUP) and close connection.

The client-side Requester can inform the server-side Responder as to whether it will honor LEASEs or not based on the presence of the L flag in the SETUP frame.

The client-side Requester that has NOT set the L flag in the SETUP frame may send requests immediately if it so desires without waiting for a LEASE from the server.

The client-side Requester that has set the L flag in the SETUP frame MUST wait for the server-side Responder to send a LEASE frame before it can send Requests.

If the server accepts the contents of the SETUP frame, it MUST send a LEASE frame if the SETUP frame set the L flag. The server-side Requester may send requests immediately upon receiving a SETUP frame that it accepts.

If the server does NOT accept the contents of the SETUP frame, the server MUST send back a SETUP_ERROR and then close the connection.

The S flag of the SETUP indicates the client requires the server to adhere to strict interpretation of the Data and Metadata of the SETUP. Anything in the Data and/or Metadata that is not understood or can be provided by the server should require the SETUP to be rejected.

The server-side Requester mirrors the LEASE requests of the client-side Requester. If a client-side Requester sets the L flag in the SETUP frame, the server side Requester MUST wait for a LEASE frame from the client-side Responder before it can send a request. The client-side Responder MUST send a LEASE frame after a SETUP frame with the L flag set.

A client assumes a SETUP is accepted if it receives a response to a request, a LEASE frame, or if it sees a REQUEST type.

A client assumes a SETUP is rejected if it receives a SETUP_ERROR.

Until connection establishment is complete, a Requester MUST NOT send any Request frames.

Until connection establishment is complete, a Responder MUST NOT emit any RESPONSE frames.

Negotiation

The assumption is that the client will be dictating to the server what it desires to do. The server will decide to support that SETUP (accept it) or not (reject it). The SETUP_ERROR error code indicates the reason for the rejection.

Sequences without LEASE

The possible sequences without LEASE are below.

  1. Client-side Request, Server-side accepts SETUP
    • Client connects & sends SETUP & sends REQUEST
    • Server accepts SETUP, handles REQUEST, sends back normal sequence based on REQUEST type
  2. Client-side Request, Server-side rejects SETUP
    • Client connects & sends SETUP & sends REQUEST
    • Server rejects SETUP, sends back SETUP_ERROR, closes connection
  3. Server-side Request, Server-side accepts SETUP
    • Client connects & sends SETUP
    • Server accepts SETUP, sends back REQUEST type
  4. Server-side Request, Server-side rejects SETUP
    • Client connects & sends SETUP
    • Server rejects SETUP, sends back SETUP_ERROR, closes connection

Sequences with LEASE

The possible sequences with LEASE are below.

  1. Client-side Request, Server-side accepts SETUP
    • Client connects & sends SETUP with L flag
    • Server accepts SETUP, sends back LEASE frame
    • Client-side sends REQUEST
  2. Client-side Request, Server-side rejects SETUP
    • Client connects & sends SETUP with L flag
    • Server rejects SETUP, sends back SETUP_ERROR, closes connection
  3. Server-side Request, Server-side accepts SETUP
    • Client connects & sends SETUP with L flag
    • Server accepts SETUP, sends back LEASE frame
    • Client sends LEASE frame
    • Server sends REQUEST
  4. Server-side Request, Server-side rejects SETUP
    • Client connects & sends SETUP with L flag
    • Server rejects SETUP, sends back SETUP_ERROR, closes connection

Fragmentation And Reassembly

RESPONSE frames may represent a large object and MAY need to be fragmented to fit within the Frame Data size. When this occurs, the RESPONSE F flag indicates if more fragments follow this frame.

Stream Sequences and Lifetimes

In the section below, "RQ -> RS" refers to Requester sending a frame to a Responder. And "RS -> RQ" refers to Responder sending a frame to a Requester.

In the section below, "*" refers to 0 or more and "+" refers to 1 or more.

Request Response

  1. RQ -> RS: REQUEST_RESPONSE
  2. RS -> RQ: RESPONSE with COMPLETE

or

  1. RQ -> RS: REQUEST_RESPONSE
  2. RS -> RQ: ERROR

or

  1. RQ -> RS: REQUEST_RESPONSE
  2. RQ -> RS: CANCEL

Upon sending a response, the stream is terminated on the Responder.

Upon receiving a CANCEL, the stream is terminated on the Responder and the response SHOULD not be sent.

Upon sending a CANCEL, the stream is terminated on the Requester.

Upon receiving a COMPLETE or ERROR, the stream is terminated on the Requester.

Request Fire-n-Forget

  1. RQ -> RS: REQUEST_FNF

Upon reception, the stream is terminated by the Responder.

Upon being sent, the stream is terminated by the Requester.

REQUEST_FNF are assumed to be best effort and MAY not be processed due to: (1) SETUP rejection, (2) mis-formatting, (3) etc.

Request Stream

  1. RQ -> RS: REQUEST_STREAM
  2. RS -> RQ: RESPONSE*
  3. RS -> RQ: ERROR

or

  1. RQ -> RS: REQUEST_STREAM
  2. RS -> RQ: RESPONSE*
  3. RS -> RQ: RESPONSE with COMPLETE

or

  1. RQ -> RS: REQUEST_STREAM
  2. RS -> RQ: RESPONSE*
  3. RQ -> RS: CANCEL

At any time, a client may send REQUEST_N frames.

Upon receiving a CANCEL, the stream is terminated on the Responder.

Upon sending a CANCEL, the stream is terminated on the Requester.

Upon receiving a COMPLETE or ERROR, the stream is terminated on the Requester.

Upon sending a COMPLETE or ERROR, the stream is terminated on the Responder.

Request Subscription

  1. RQ -> RS: REQUEST_SUBSCRIPTION
  2. RS -> RQ: RESPONSE*

or

  1. RQ -> RS: REQUEST_SUBSCRIPTION
  2. RS -> RQ: RESPONSE*
  3. RS -> RQ: ERROR

or

  1. RQ -> RS: REQUEST_SUBSCRIPTION
  2. RS -> RQ: RESPONSE*
  3. RQ -> RS: CANCEL

At any time, a client may send REQUEST_N frames.

Upon receiving a CANCEL, the stream is terminated on the Responder.

Upon sending a CANCEL, the stream is terminated on the Requester.

Upon receiving a ERROR, the stream is terminated on the Requester.

Upon sending a ERROR, the stream is terminated on the Responder.

Per Stream State

Requester

  1. CLOSED: implicit starting/ending state of all stream IDs
  2. Requested (sent REQUEST_*)
  3. CLOSED (received COMPLETE or sent REQUEST_FNF)
  4. CLOSED (received ERROR)

Responder

  1. CLOSED: implicit starting/ending state of all stream IDs
  2. Responding: sending RESPONSEs and processing REQUEST_N
  3. CLOSED (received CANCEL)
  4. CLOSED (sent COMPLETE or received REQUEST_FNF)
  5. CLOSED (sent ERROR)

Flow Control

Reactive Stream Semantics

Reactive Stream semantics for flow control of Streams and Subscriptions.

Lease Semantics

Requester MUST respect the LEASE contract. The Requester MUST NOT send more than Number of Requests specified in the LEASE frame within the Time-To-Live value in the LEASE.

A Responder that receives a REQUEST that it can not honor due to LEASE restrictions MUST ignore the REQUEST. This includes an initial LEASE sent as part of Connection Establishment.

Handling the Unexpected

This protocol attempts to be very lenient in processing of received frames and SHOULD ignore conditions that do not make sense given the current context. Clarifications are given below:

  1. TCP half-open connections (and WebSockets) or other dead transports are detectable by lack of KEEPALIVE frames as specified under Keepalive Frame. The decision to close a connection due to inactivity is the applications choice.
  2. Request keepalive and timeout semantics are the responsibility of the application.
  3. Lack of REQUEST_N frames that stops a stream is an application concern and SHALL NOT be handled by the protocol.
  4. Lack of LEASE frames that stops new Requests is an application concern and SHALL NOT be handled by the protocol.
  5. If a RESPONSE for a REQUEST_RESPONSE is received that does not have a COMPLETE flag set, the implementation MUST assume it is set and act accordingly.
  6. Reassembly of RESPONSES MUST assume the possibility of an infinite stream.
  7. Stream ID values MAY be re-used after completion or error of a stream.
  8. A RESPONSE with both F and C flags set, implicitly ignores the F flag.
  9. All other received frames that are not accounted for in previous sections MUST be ignored. Thus, for example:
    1. Receiving a Request frame on a Stream ID that is already in use MUST be ignored.
    2. Receiving a CANCEL on an unknown Stream ID (including 0) MUST be ignored.
    3. Receiving an ERROR on an unknown Stream ID (including 0) MUST be ignored.
    4. Receiving a RESPONSE on an unknown Stream ID (including 0) MUST be ignored.
    5. Receiving a METADATA_PUSH on an unknown Stream ID MUST be ignored.
    6. A server MUST ignore a SETUP frame after it has accepted a previous SETUP.
    7. A server MUST ignore a SETUP_ERROR frame.
    8. A client MUST ignore a SETUP_ERROR after it has completed connection establishment.
    9. A client MUST ignore a SETUP frame.
To Be Specified

TODO

  • Stream ID should maybe be renamed to Request ID.
  • naming
    • Connection instance
      • Requester instance
      • Responder instance
  • Handling the unexpected section