Skip to content

Update SignalR transport protocol spec #13916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Sep 27, 2019
Merged

Update SignalR transport protocol spec #13916

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
69d6bec
update transport protocol spec
mikaelm12 Sep 11, 2019
3556f9b
english
mikaelm12 Sep 11, 2019
9982ec6
update spec
mikaelm12 Sep 13, 2019
2c31438
Update src/SignalR/docs/specs/TransportProtocols.md
mikaelm12 Sep 16, 2019
3f297a4
Update src/SignalR/docs/specs/TransportProtocols.md
mikaelm12 Sep 17, 2019
c169132
wording and first attempt at versioning
BrennanConroy Sep 19, 2019
f3257f3
try
BrennanConroy Sep 19, 2019
20098dd
header
BrennanConroy Sep 19, 2019
407d494
small modifications
BrennanConroy Sep 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions src/SignalR/docs/specs/TransportProtocols.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,21 @@ A transport is required to have the following attributes:

The only transport which fully implements the duplex requirement is WebSockets, the others are "half-transports" which implement one end of the duplex connection. They are used in combination to achieve a duplex connection.

Throughout this document, the term `[endpoint-base]` is used to refer to the route assigned to a particular end point. The term `[connection-id]` is used to refer to the connection ID provided by the `POST [endpoint-base]/negotiate` request.
Throughout this document, the term `[endpoint-base]` is used to refer to the route assigned to a particular end point. The terms `connection-id` and `connectionToken` are used to refer to the connection ID and connection token provided by the `POST [endpoint-base]/negotiate` request.

**NOTE on errors:** In all error cases, by default, the detailed exception message is **never** provided; a short description string may be provided. However, an application developer may elect to allow detailed exception messages to be emitted, which should only be used in the `Development` environment. Unexpected errors are communicated by HTTP `500 Server Error` status codes or WebSockets non-`1000 Normal Closure` close frames; in these cases the connection should be considered to be terminated.

## `POST [endpoint-base]/negotiate` request

The `POST [endpoint-base]/negotiate` request is used to establish a connection between the client and the server. The content type of the response is `application/json`. The response to the `POST [endpoint-base]/negotiate` request contains one of three types of responses:
The `POST [endpoint-base]/negotiate` request is used to establish a connection between the client and the server. There is an optional `negotiateVersion` query string parameter that can be added to the negotiate post request. This determines the protocol version between the server and the client. If omitted, the version is defaulted to zero. Servers can configure their minimum supported protocol version which will determine how they respond to old clients. If configured to be greater than the clients requested version, the server will send an error response indicating that the requested version is not supported by the server. If the server supports the requested protocol version it will set the "negotiateVersion" on the response to the clients version. If a server is configured to accept clients using protocol version 0, then the `connectionToken` is omitted and only the `connectionId` is used internally. The content type of the response is `application/json`. The response to the `POST [endpoint-base]/negotiate` request contains one of three types of responses:

1. A response that contains the `connectionId` which will be used to identify the connection on the server and the list of the transports supported by the server.
1. A response that contains the `connectionToken` which will be used to identify the connection on the server and the list of the transports supported by the server. The `connectionToken` should be kept secret. It also contains the `connectionId` which is a public id

```json
{
"connectionToken":"05265228-1e2c-46c5-82a1-6a5bcc3f0143",
"connectionId":"807809a5-31bf-470d-9e23-afaee35d8a0d",
"negotiateVersion":1,
"availableTransports":[
{
"transport": "WebSockets",
Expand All @@ -44,7 +46,9 @@ The `POST [endpoint-base]/negotiate` request is used to establish a connection b

The payload returned from this endpoint provides the following data:

* The `connectionId` which is **required** by the Long Polling and Server-Sent Events transports (in order to correlate sends and receives).
* The `connectionToken` which is **required** by the Long Polling and Server-Sent Events transports (in order to correlate sends and receives).
* The `connectionId` which is the id by which other clients can refer to it.
* The `negotiateVersion` which is the negotiation protocol version being used between the server and client.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This name is odd to me. It's more like a protocolVersion since it's the version of the protocol, not the version of "negotiation".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think most of us preferred protocolVersion, but shied away from from using that since we thought what what the old client used and we wanted to be able to easily distinguish clients from request logs.

It turns out the old client used clientProtocol as the QS parameter, so I'm also in support of protocolVersion.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ASP.NET SignalR negotiate response includes protocolVersion

https://github.com/SignalR/SignalR/blob/fc475fa161eaf94150c4aaa4ba71830fd976eb6c/src/Microsoft.AspNet.SignalR.Client/NegotiationResponse.cs#L14

* The `availableTransports` list which describes the transports the server supports. For each transport, the name of the transport (`transport`) is listed, as is a list of "transfer formats" supported by the transport (`transferFormats`)


Expand Down Expand Up @@ -136,10 +140,10 @@ Long Polling requires that the client poll the server for new messages. Unlike t

A Poll is established by sending an HTTP GET request to `[endpoint-base]` with the following query string parameters

* `id` (Required) - The Connection ID of the destination connection.
* `id` (Required) - The Connection Token of the destination connection.

When data is available, the server responds with a body in one of the two formats below (depending upon the value of the `Accept` header). The response may be chunked, as per the chunked encoding part of the HTTP spec.

If the `id` parameter is missing, a `400 Bad Request` response is returned. If there is no connection with the ID specified in `id`, a `404 Not Found` response is returned.

When the client has finished with the connection, it can issue a `DELETE` request to `[endpoint-base]` (with the `id` in the querystring) to gracefully terminate the connection. The server will complete the latest poll with `204` to indicate that it has shut down.
When the client has finished with the connection, it can issue a `DELETE` request to `[endpoint-base]` (with the `id` in the query string) to gracefully terminate the connection. The server will complete the latest poll with `204` to indicate that it has shut down.