Transmission protocol - Garados007/srpc GitHub Wiki

This protocol is used by the sRPC client and server to transmit single messages over the streams.

Each message has a 4 byte header with an int32 (lowest byte first) encoded length of the message itself. The request message that is sent on the wire looks like this:

message NetworkRequest {
	// the name of the api function to request
	string api_function = 1;
	// the request object with the data
	google.protobuf.Any request = 2;
	// the token to identify the response with the request
	int64 token = 3;
	// a list of token ids which has the request canceld.
	// The server should now stop the computation of the response.
	// There is no response message needed.
	repeated int64 cancelRequests = 4;
}

The api_function defines the RPC call. This is inherited from the service declaration in the proto file. The argument of this RPC call is packed in request.

The response message that is sent on the wire looks like this:

message NetworkResponse {
	// the response object with the data
	google.protobuf.Any response = 2;
	// the token to identify this response
	int64 token = 3;
}

Token

Both request and response send a single int64 token. This is used to identify the response with the request. The tokens are created from the client at the same time when the request is created. The server put the same token from the request in the response.

The current implementation increments the token with each request but there is no need to do so. The tokens can be reused but there should never two messages with the same token at the same time (this will confuse the client).

Cancel Requests

This is introduced in Version 2.0.0. With this requests can be cancelled by the user or the server. For this a special field is added to the NetworkRequest. This contains all the Tokens of messages that are cancelled by the user.

Client cancels its requests

• the client send the server a NetworkRequest with the field cancelRequests set.
• client cancels its awaiting task, cleanup its stuff and continue the execution
  • in the awaiting task a TaskCancelledException is raised
• server receives the cancellation request
• it cancels its execution of the request and cleanup its stuff

Server cancels its computation of a request

• if an unhandled TaskCanncelledException was raised and returned to the api the server send an empty response to the client with the same Token as the request
• the server cleanups its stuff
• the client receives the empty message. If its awaiting on this response it will call a TaskCancelledException on its own side.