package async_rpc_kernel

A bit of information about requests and responses. One can subscribe to these events for a Connection.t to implement some kinds of metrics or tracing.

When subscribing to events, the expected flow for received queries -> sent responses should look like one of the following cases.

1. Received query and sent response with matching rpc description and id. The response depends on the kind of RPC and result.

   1. For one-way queries, the result is synthetic in that nothing is sent over the network
   2. For an ordinary RPC, the responses may be Single_succeeded, Single_or_streaming_rpc_error_or_exn, Single_or_streaming_user_defined_error, or in rare cases, Expert_single_succeeded_or_failed
   3. If a streaming RPC (e.g. a pipe or state RPC) fails (e.g. an exn or authorization failure), there is a single Single_or_streaming_rpc_error_or_exn response. If it returns an initial error, there is a single Single_or_streaming_user_defined_error response

2. Received query and many streaming responses sent, all with the same description and id.

   1. The first response would be marked as Streaming_initial
   2. Followed by zero or more responses marked Streaming_update
   3. And finished by a response marked Streaming_closed
   4. An Abort_streaming_rpc_query with the same id is a request from the client to stop streaming early and may arrive at any time after the Streaming_initial message
3. In exceptional circumstances, e.g. if the response would be too large, there will be a Failed_to_send error and this may, for example, also lead to no Streaming_closed message ever being sent.
4. In exceptional cases, there will be no response. For example, if there is some kind of critical error that closes the connection, or if an expert unknown rpc handler fires.

The difference between a Single_or_streaming_rpc_error_or_exn and Single_or_streaming_user_defined_error is that the former comes from errors like an implementation raising or returning unauthorized whereas the latter comes from an implementation returning an Error _ response, for those created with Rpc.Rpc.create_result.

The flow for sent queries -> received responses should look like one of the following:

1. Sent query immediately followed by a received One_way_so_no_response which is synthetic in that no response is received over the wire.
2. Sent query followed by zero or more Partial_response events followed by one finished event, either Response_finished_ok, Response_finished_rpc_error_or_exn, Response_finished_user_defined_error, or Response_finished_expert_uninterpreted.
3. In exceptional circumstances, there will be no corresponding Response to a Query, for example if the connection is lost or if the server never responds.