Drop requirement to delete cargo when relayer acknowledges receipt

diagrams/rs008/cogrpc.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package relaynet.cogrpc;
+
+service CargoRelay {
+    rpc CollectCargo (stream CargoDelivery) returns (stream CargoDeliveryAck);
+
+    rpc DeliverCargo (stream CargoDeliveryAck) returns (stream CargoDelivery);
+}
+
+message CargoDelivery {
+    string id = 1;
+    bytes cargo = 2;
+}
+
+message CargoDeliveryAck {
+    string id = 1;
+}

index.md

@@ -13,7 +13,7 @@ The following specifications provide the foundation of the network and are there
 - [RS-001 (RAMF)](rs001-ramf.md) defines the _Relaynet Abstract Message Format_, an efficient binary format used to serialize messages.
 - [RS-002 (Relaynet PKI)](rs002-pki.md) defines how to use the certificates for endpoints and gateways.
 - [RS-003 (Key Agreement)](rs003-key-agreement.md) defines the key agreement protocol to establish and protect sessions.
-- [RS-004 (CoSocket)](rs004-cosocket.md) is the part of the technology that helps transport the data using alternative methods like sneakernets.
+- [RS-008 (CogRPC)](rs008-cogrpc.md) is the part of the technology that helps transport the data using alternative methods like sneakernets.
 - [RS-016 (PoWebSocket)](rs016-powebsocket.md) defines a protocol that connects applications to the Relaynet network.
 - [RS-007 (PoHTTP)](rs007-pohttp.md) defines a protocol that connects Relaynet to the Internet.
 - [RS-018 (Cryptographic Algorithms)](rs018-algorithms.md) defines the cryptographic algorithms that can be used in Relaynet.

rs000-core.md

@@ -118,14 +118,11 @@ The payload ciphertext MUST be encrypted. The corresponding plaintext MUST encap
 1. A 32-bit unsigned integer (4 octets) representing the length of the parcel.
 1. The parcel serialized in the RAMF.
 
-#### Cargo Collection Authorization (CCA)
+#### Cargo Collection Authorization (CCA) {#cca}
 
 A Cargo Collection Authorization (CCA) is a RAMF-serialized message whereby Gateway A allows a relayer to collect cargo on its behalf from Gateway B. Its concrete message type is the octet `0x44`. This is to be eventually used as described in the [cargo relay binding](#cargo-relay-binding).
 
-The payload ciphertext MUST be encrypted. The corresponding plaintext MUST contain the following information:
-
-- Any [_Parcel Delivery Deauthorizations_ (PDD)](rs002-pki.md#parcel-delivery-deauthorization-pdd) issued by Gateway A's endpoints or Gateway A itself to revoke [PDAs](rs002-pki.md#parcel-delivery-authorization-pda).
-- Binding-level constraints to authenticate the relayer, like expecting a specific _Certificate Authority_ in its TLS certificate chain (or equivalent). Gateway B MUST close the connection if these constraints are not met.
+The payload ciphertext MUST be encrypted. The corresponding plaintext MAY contain any [_Parcel Delivery Deauthorizations_ (PDD)](rs002-pki.md#parcel-delivery-deauthorization-pdd) issued by Gateway A's endpoints or Gateway A itself to revoke [PDAs](rs002-pki.md#parcel-delivery-authorization-pda).
 
 The payload plaintext MUST be serialized with [Protocol Buffers v3](https://developers.google.com/protocol-buffers/docs/proto3) using the `CargoCollectionAuthorization` message as defined below:
 
@@ -134,15 +131,10 @@ syntax = "proto3";
 
 package relaynet.messaging.gateway;
 
-import "google/protobuf/any.proto";
 import "google/protobuf/timestamp.proto";
 
 message CargoCollectionAuthorization {
     repeated ParcelDeliveryDeauthorization parcel_delivery_deauthorizations = 1;
-
-    // The key MUST be the name of the binding (lower case) and the value MUST
-    // be defined by the binding.
-    map<string, google.protobuf.Any> relayer_constraints = 2;
 }
 
 message ParcelDeliveryDeauthorization {
@@ -152,6 +144,29 @@ message ParcelDeliveryDeauthorization {
 }
 ```
 
+#### Parcel Collection Acknowledgement (PCA) {#pca}
+
+A Parcel Collection Acknowledgement (PCA) is a RAMF-serialized message used to signal to the peer gateway that the specified parcel(s) has been received and safely stored; its concrete message type is the octet `0x51`. The gateway that sent the original parcels MAY permanently delete such parcels at that point.
+
+The payload plaintext MUST be serialized with [Protocol Buffers v3](https://developers.google.com/protocol-buffers/docs/proto3) using the `ParcelCollectionAcknowledgement` message as defined below:
+
+```proto
+syntax = "proto3";
+
+package relaynet.messaging.gateway;
+
+message ParcelCollectionAcknowledgement {
+    repeated CollectedParcel parcel = 1;
+}
+
+message CollectedParcel {
+    string origin_endpoint_private_address = 1;
+    string parcel_id = 2;
+}
+```
+
+`origin_endpoint_private_address` represents the private node address of the endpoint sending the parcel and `parcel_id` represents the RAMF message id of said parcel.
+
 ## Message Transport Bindings
 
 A message transport binding, or simply _binding_, defines the [adjacent-layer interactions](https://upskilld.com/learn/same-layer-and-adjacent-layer-interactions/) in Relaynet. [Parcel delivery bindings](#parcel-delivery-binding) define the communication between endpoints and gateways, and [cargo relay bindings](#cargo-relay-binding) define the communication between gateways and relayers. This document describes the requirements applicable to all bindings, but does not define any concrete binding.
@@ -217,26 +232,19 @@ The gateway MUST NOT start delivering parcels until the endpoint has signalled t
 
 This is a protocol that establishes a _Cargo Relay Connection_ (CRC) between a gateway and a relayer with the primary purpose of exchanging cargo bidirectionally.
 
-The action of transmitting a cargo over a CRC is called _hop_, and the action of transmitting a cargo from its origin gateway to its target gateway is _relay_. There are usually two hops in a relay: One from the origin gateway to the relayer, and another from the relayer to the target gateway. A relaying gateway receiving cargo for another gateway MAY _forward_ it to its target gateway, which would involve an extra hop.
+The action of transmitting a cargo over a CRC is called _hop_, and the action of transmitting a cargo from its origin gateway to its target gateway is _relay_. There are at least two hops in a relay: One from the origin gateway to the relayer, and another from the relayer to the target gateway.
 
 Completing one relay MAY involve hops with different bindings. For example, the CRC between a user gateway and a relayer could use [CoSocket](rs004-cosocket.md), whilst the CRC between the relayer and the relaying gateway could use [CogRPC](rs008-cogrpc.md).
 
-The node sending a cargo MUST NOT remove it until the peer has acknowledged its receipt. The acknowledgement MUST be sent after the cargo is safely stored -- Consequently, if the cargo is being saved to a local disk, its receipt MUST be acknowledged after calling [`fdatasync`](https://linux.die.net/man/2/fdatasync) (on Unix-like systems) or [`FlushFileBuffers`](https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-flushfilebuffers) (on Windows).
+The gateway sending a cargo MUST NOT remove it until the target gateway has acknowledged its receipt. The acknowledgment MAY be received via a CRC or an Internet-based PDC (once the two gateways can communicate directly over the Internet). The recipient MUST send the acknowledgement after the cargo is safely stored -- Consequently, if the cargo is being saved to a local disk, its receipt MUST be acknowledged after calling [`fdatasync`](https://linux.die.net/man/2/fdatasync) (on Unix-like systems) or [`FlushFileBuffers`](https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-flushfilebuffers) (on Windows).
 
 A gateway MAY provide the relayer with a CCA so that the relayer can collect cargo from its peer gateway.
 
-A user gateway MAY require the relayer to provide a CCA from the relaying gateway, but a relaying gateway MUST require at least one CCA because:
-
-- The relaying gateway needs the user gateway's certificate to identify the parcels that belong to the user gateway (user gateway's certificate is part of the PDA).
-- The relaying gateway could not delete a cargo after delivering it if it does not have some guarantee that the cargo could reach its destination.
+A user gateway MAY require the relayer to provide a CCA from the relaying gateway, but a relaying gateway MUST require at least one CCA because it needs the user gateway's certificate to identify the parcels that belong to the user gateway (the user gateway's certificate is part of the PDA certification chain).
 
 The relayer SHOULD deliver the cargo and then wait a few seconds before collecting cargo from the gateway, in case there are any responses to the messages in the cargo that was delivered.
 
-When the connection spans different computers, the relayer MUST initiate a handshake with the gateway by having it sign a nonce with each Relaynet PKI key it claims to have, as shown in the following sequence diagram. (The CRC could be local to a computer if, for example, the cargo is being directly saved to and retrieved from a storage media.)
-
-![](diagrams/rs000/crc-handshake-sequence.png)
-
-Note that relayers are not assigned Relaynet PKI certificates, but per the requirements above for bindings in general, TLS certificates or equivalent must be used when the connection spans different computers. In such cases, the relayer MUST provide a valid client- or server-side certificate when it acts as client or server, respectively, and the gateway MUST enforce any authentication-related constraints placed by its peer gateway in the CCA (e.g., which Certificate Authorities should be regarded valid).
+Note that relayers are not assigned Relaynet PKI certificates, but per the requirements above for bindings in general, TLS certificates or equivalent must be used when the connection spans different computers. In such cases, the relayer MUST provide a valid client- or server-side certificate when it acts as client or server, respectively.
 
 ## Open Questions
 

rs001-ramf.md

@@ -74,8 +74,9 @@ The following concrete types have been reserved by other Relaynet specifications
 - `0x10` for [certificate rotation](rs002-pki.md#certificate-and-key-rotation).
 - `0x11` for [gateway certificate revocation](rs002-pki.md#gateway-certificate-revocation-gcr).
 - `0x43` ("C" in ASCII) for [cargoes](rs000-core.md#cargo).
-- `0x44` for [cargo collection authorizations](rs000-core.md#cargo-collection-authorization-cca).
+- `0x44` for [cargo collection authorizations](rs000-core.md#cca).
 - `0x50` ("P" in ASCII) for [parcels](rs000-core.md#parcel).
+- `0x51` for [parcel collection acknowledgments](rs000-core.md#pca).
 
 ## Open Issues
 

rs002-pki.md

@@ -128,7 +128,7 @@ An endpoint MUST use the [message transport binding](rs000-core.md#message-trans
 - (Optional) Serial numbers of the PDAs to revoke. It may be absent to revoke all the PDAs issued by the endpoint.
 - (Required) Expiry date of the deauthorization. If revoking all PDAs from the endpoint, this MUST be the expiry date of the endpoint certificate. If revoking a specific PDA, this MUST be the expiry date of the PDA.
 
-Gateways MUST include all their active PDDs in their [_Cargo Collection Authorizations_](rs000-core.md#cargo-collection-authorization-cca), and they MUST enforce PDDs for as long as they are active.
+Gateways MUST include all their active PDDs in their [_Cargo Collection Authorizations_](rs000-core.md#cca), and they MUST enforce PDDs for as long as they are active.
 
 Relaying gateways MAY cache PDDs until they expire in order to refuse future parcels whose PDA has been revoked.
 

rs004-cosocket.md

@@ -1,11 +1,12 @@
 ---
+nav_exclude: true
 permalink: /RS-004
 ---
 # Cargo Relay over TCP/Unix Sockets (CoSocket)
 {: .no_toc }
 
 - Id: RS-004.
-- Status: Working draft.
+- Status: Abandoned.
 - Type: Implementation.
 - Proof of concept: https://github.com/relaynet/poc/tree/master/CoSocket
 
@@ -70,7 +71,7 @@ This packet is sent by the relayer when the signatures were successfully verifie
 
 #### Cargo Collection Request
 
-This packet encapsulates a [Cargo Collection Authorization (CCA)](rs000-core.md#cargo-collection-authorization-cca) and represents a request to collect cargo for a specific gateway.
+This packet encapsulates a [Cargo Collection Authorization (CCA)](rs000-core.md#cca) and represents a request to collect cargo for a specific gateway.
 
 A relayer MUST send this packet to a gateway to indicate it is ready to receive cargo and to prove it is authorized to receive cargo for the gateway in the CCA.
 

rs008-cogrpc.md

@@ -1,9 +1,60 @@
 ---
-nav_exclude: true
 permalink: /RS-008
 ---
 # CogRPC: Cargo Relay over gRPC
+{: .no_toc }
 
 - Id: RS-008.
-- Status: Deprecated.
+- Status: Draft.
 - Type: Implementation.
+
+## Abstract
+{: .no_toc }
+
+This document describes CogRPC (pronounced _Co-Jee-Arr-Pee-See_), a [cargo relay binding](rs000-core.md#cargo-relay-binding) on top of [gRPC](https://grpc.io/).
+
+## Table of contents
+{: .no_toc }
+
+1. TOC
+{:toc}
+
+## Introduction
+
+As a cargo relay binding, CogRPC's objective is to establish a Cargo Relay Connection (CRC) between a relayer and a gateway so they can exchange cargo.
+
+When a CRC is established between a local gateway and a relayer, the gateway and the relayer act as the client and the server, respectively. Similarly, when a CRC is established between a relaying gateway and a relayer, they act as the server and the client, respectively.
+
+This binding defines multiple message types and RPCs under a single gRPC service called `CargoRelay`. The gRPC interface described by this binding is defined in full in the form of Protocol Buffers at the end of this document.
+
+The client is responsible for initiating the delivery and collection of parcels using the corresponding RPC. Note that per [RS-000](./rs000-core.md), it is recommended that the client sends the cargo before attempting to collect any cargo.
+
+## Remote Procedure Calls (RPCs) {#rpcs}
+
+The messages sent to and received from the gRPC services below MUST be serialized with Protocol Buffers v3.
+
+### `CollectCargo`
+
+This bidirectional streaming RPC MUST be used to deliver cargo to the server. The client MUST send zero or more [RAMF](rs001-ramf.md)-serialized cargo messages and the server MUST acknowledge the receipt of each cargo per the requirements and recommendations in RS-000.
+
+The cargo sent to the server MAY originate in different gateways.
+
+### `DeliverCargo`
+
+This bidirectional streaming RPC MUST be used to collect cargo from the server. The server MUST send zero or more [RAMF](rs001-ramf.md)-serialized cargo messages and the client MUST acknowledge the receipt of each cargo per the requirements and recommendations in RS-000.
+
+This call MUST be authenticated by setting the `Authorization` metadata to the string `Relaynet-CCA ${crcBase64}`, where `${crcBase64}` is the Base64-encoded serialization of a valid [Cargo Collection Authorization (CCA)](./rs000-core.md#cca). As a consequence, each call is bound to exactly one target gateway.
+
+## Acknowledgement Messages
+
+A node sending cargo MUST attach a UUID4 to each individual message. The recipient MUST attach such identifier to each acknowledgement message.
+
+## Protocol Buffers Package Definition
+
+```proto
+{% include_relative diagrams/rs008/cogrpc.proto %}
+```
+
+## Relevant Specifications
+
+[Relaynet Core (RS-000)](rs000-core.md) defines the requirements for [message transport bindings](rs000-core.md#message-transport-bindings) in general and [cargo relay bindings](rs000-core.md#cargo-relay-binding) specifically, all of which apply to CogRPC. Amongst other things, it defines the use Transport Layer Security (TLS) or equivalent, as well as when it is safe to return acknowledgement messages.

rs013-pubsub.md

@@ -34,5 +34,5 @@ A _relaying gateway_ could subscribe to the topics relevant to its peer gateways
 ## Messaging Protocols
 
 - Broadcast parcels could be unencrypted (CMS type "data"), or encrypted with one or more certificates (CMS type "enveloped data").
-- The [Cargo Collection Authorization](rs000-core.md#cargo-collection-authorization-cca) MUST include zero or more topic subscriptions.
+- The [Cargo Collection Authorization](rs000-core.md#cca) MUST include zero or more topic subscriptions.
 - A topic subscription is a structure that contains a topic address (potentially using glob patterns) and any conditions that the broadcast parcel must meet, such as having a specific origin endpoint (by address).