Processing of Cargo Collection Authorizations (CCAs) is insufficiently defined

[gnarea]

Summary

The core spec defines the structure of a CCA and the CogRPC spec defines how a courier should send it to a public gateway when collecting cargoes, but the process to send the CCA from a private gateway to a courier is not defined.

Proposed solution

Per the current specs, the client (e.g., a private gateway, a courier) initiates a request to collect cargo from the server (e.g., a courier, a public gateway) by including the CCA in the request headers. The server will then send zero or more cargoes to the client, each of which the client should acknowledge.

To solve this issue, we could change the cargo collection process to do the following instead:

The client should send the CCA as a gRPC message and the server should return zero or more cargoes in return. And instead of having the server send an acknowledgement, it'd send a "collection complete" message when no further cargoes are to be sent for a given CCA.

In other words, the CollectCargo RPC will support the following messages:

• CargoCollectionAuthorization (1 or more per call), sent by the client.
• CargoDelivery (0 or more per CargoCollectionAuthorization), sent by the server. This message encapsulates one cargo message.
• CargoDeliveryAck (0 or 1 per CargoDelivery), sent by the client.
• CargoDeliveryComplete (exactly 1 per CargoCollectionAuthorization), sent by the server.

Note that the cargo delivery RPC remains unchanged.

Positive side-effects

• The implementation will be simpler, since there's now two RPCs per connection: One to deliver cargo and the other to collect cargo. Previously, we had one to deliver cargo and N to collect cargo (one for each CCA).
• This will make it easier for courier apps to exchange cargo amongst them in the future: A courier app could connect to another courier as a private gateway.

Negative side-effects

• The CollectCargo gRPC method will become slightly more complicated, since we'll have to mimic polymorphism to allow the client and the server to send different types of messages -- CargoCollectionAuthorization/CargoDeliveryAck and CargoDelivery/CargoDeliveryComplete, respectively.

[gnarea]

I've been thinking further about this and hacking some code to test these changes, and I'm concerned about the complexity we'd get by adding two more message types and trying to mimic polymorphism in Protocol Buffers.

This complexity can be avoided by passing the CCA in the gRPC call metadata (analogous to an HTTP request header) and the server can signal it's done processing the CCA by ending the call (not the connection), so that's what I've done in #56.