From a920e7aa6da7605f8991a2ff6836b0ce573d2e44 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 20 Jan 2023 17:11:25 -0800 Subject: [PATCH 1/2] Update README to recommend proto3 --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 64764ef..68dfa8c 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,14 @@ and are used throughout the system. These specs define wire protocols that are used by libp2p for connectivity, security, multiplexing, and other purposes. -The protocols described below all use [protocol buffers](https://developers.google.com/protocol-buffers/docs/proto?hl=en) (aka protobuf) to define message schemas. Version `proto2` is used unless stated otherwise. +The protocols described below all use [protocol +buffers](https://developers.google.com/protocol-buffers/docs/proto?hl=en) (aka +protobuf) to define message schemas. + +Existing protocols may use `proto2`, and continue to use them. `proto3` is +recommended for new protocols. `proto3` is a simplification of `proto2` and +removes some footguns. For context and a discussion around `proto3` vs `proto2`, +see [#465](https://github.com/libp2p/specs/issues/465). - [ping][spec_ping] - Ping protocol - [autonat][spec_autonat] - NAT detection From c733210b3a6c042d01f6b39f23c0c9a3a20d3e88 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 20 Jan 2023 17:13:13 -0800 Subject: [PATCH 2/2] Make existing protocols explicit about proto2 --- fetch/README.md | 2 ++ identify/README.md | 1 + kad-dht/README.md | 2 ++ plaintext/README.md | 2 ++ pubsub/README.md | 3 +++ pubsub/gossipsub/gossipsub-v1.0-old.md | 2 ++ pubsub/gossipsub/gossipsub-v1.0.md | 2 ++ pubsub/gossipsub/gossipsub-v1.1.md | 1 + relay/circuit-v1.md | 2 ++ relay/circuit-v2.md | 6 ++++-- rendezvous/README.md | 2 ++ tls/tls.md | 2 ++ 12 files changed, 25 insertions(+), 2 deletions(-) diff --git a/fetch/README.md b/fetch/README.md index 04ec78d..f598648 100644 --- a/fetch/README.md +++ b/fetch/README.md @@ -88,6 +88,8 @@ The libp2p protocol ID for this protocol is `/libp2p/fetch/0.0.1` The messages in the Fetch protocol use on of the following protobufs (proto3 syntax): ``` +syntax = "proto2"; + message FetchRequest { string identifier = 1; } diff --git a/identify/README.md b/identify/README.md index b64ef48..2d7f141 100644 --- a/identify/README.md +++ b/identify/README.md @@ -73,6 +73,7 @@ whose values have changed. ## The Identify Message ```protobuf +syntax = "proto2"; message Identify { optional string protocolVersion = 5; optional string agentVersion = 6; diff --git a/kad-dht/README.md b/kad-dht/README.md index e74d1d1..4367d96 100644 --- a/kad-dht/README.md +++ b/kad-dht/README.md @@ -401,6 +401,8 @@ bytes, encoded as an unsigned variable length integer as defined by the All RPC messages conform to the following protobuf: ```protobuf +syntax = "proto2"; + // Record represents a dht record that contains a value // for a key value pair message Record { diff --git a/plaintext/README.md b/plaintext/README.md index d94f16e..c0e47d6 100644 --- a/plaintext/README.md +++ b/plaintext/README.md @@ -84,6 +84,8 @@ The `PublicKey` message uses the same definition [specified in the peer id spec][peer-id-spec-pubkey-message]. For reference, it is defined as follows: ``` protobuf +syntax = "proto2"; + enum KeyType { RSA = 0; Ed25519 = 1; diff --git a/pubsub/README.md b/pubsub/README.md index 3a61163..120b206 100644 --- a/pubsub/README.md +++ b/pubsub/README.md @@ -90,6 +90,7 @@ messages between participating peers. The `RPC` protobuf is as follows: ```protobuf +syntax = "proto2"; message RPC { repeated SubOpts subscriptions = 1; repeated Message publish = 2; @@ -112,6 +113,7 @@ false signifies 'unsubscribe'. The RPC message can contain zero or more messages of type 'Message'. The Message protobuf looks like this: ```protobuf +syntax = "proto2"; message Message { optional string from = 1; optional bytes data = 2; @@ -341,6 +343,7 @@ and may be removed once used. The `TopicDescriptor` protobuf is as follows: ```protobuf +syntax = "proto2"; message TopicDescriptor { optional string name = 1; // AuthOpts and EncOpts are unused as of Oct 2018, but diff --git a/pubsub/gossipsub/gossipsub-v1.0-old.md b/pubsub/gossipsub/gossipsub-v1.0-old.md index 98cb849..a91003e 100644 --- a/pubsub/gossipsub/gossipsub-v1.0-old.md +++ b/pubsub/gossipsub/gossipsub-v1.0-old.md @@ -375,6 +375,8 @@ control messages. The four control messages are `ControlIHave` for `IHAVE` messa The protobuf is as follows: ```protobuf +syntax = "proto2"; + message RPC { // ... optional ControlMessage control = 3; diff --git a/pubsub/gossipsub/gossipsub-v1.0.md b/pubsub/gossipsub/gossipsub-v1.0.md index 52118b5..db8fdbe 100644 --- a/pubsub/gossipsub/gossipsub-v1.0.md +++ b/pubsub/gossipsub/gossipsub-v1.0.md @@ -506,6 +506,8 @@ The four control messages are `ControlIHave` for [`IHAVE`](#ihave) messages, The protobuf is as follows: ```protobuf +syntax = "proto2"; + message RPC { // ... see definition in pubsub interface spec optional ControlMessage control = 3; diff --git a/pubsub/gossipsub/gossipsub-v1.1.md b/pubsub/gossipsub/gossipsub-v1.1.md index 75c8a01..3d48d39 100644 --- a/pubsub/gossipsub/gossipsub-v1.1.md +++ b/pubsub/gossipsub/gossipsub-v1.1.md @@ -129,6 +129,7 @@ In this case, the pruned peer will have to rely on the ambient peer discovery se The `ControlPrune` message is extended with a `peers` field as follows. ```protobuf +syntax = "proto2"; message ControlPrune { optional string topicID = 1; repeated PeerInfo peers = 2; // gossipsub v1.1 PX diff --git a/relay/circuit-v1.md b/relay/circuit-v1.md index 75bc85f..d11b6c3 100644 --- a/relay/circuit-v1.md +++ b/relay/circuit-v1.md @@ -140,6 +140,8 @@ We start the description of the Wire format by illustrating a possible flow scen Every message in the relay protocol uses the following protobuf: ``` +syntax = "proto2"; + message CircuitRelay { enum Status { diff --git a/relay/circuit-v2.md b/relay/circuit-v2.md index feb3fc9..1e9f8d4 100644 --- a/relay/circuit-v2.md +++ b/relay/circuit-v2.md @@ -347,7 +347,8 @@ The voucher itself is a [Signed Envelope](../RFC/0002-signed-envelopes.md). The envelope domain is `libp2p-relay-rsvp` and uses the multicodec code `0x0302`. The payload of the envelope has the following form, in canonicalized protobuf format: -``` +```protobuf +syntax = "proto2"; message Voucher { required bytes relay = 1; required bytes peer = 2; @@ -363,7 +364,8 @@ The wire representation is canonicalized, where elements of the message are writ ## Protobuf -``` +```protobuf +syntax = "proto2"; message HopMessage { enum Type { RESERVE = 0; diff --git a/rendezvous/README.md b/rendezvous/README.md index 862eaeb..66584c7 100644 --- a/rendezvous/README.md +++ b/rendezvous/README.md @@ -191,6 +191,8 @@ topic. ### Protobuf ```protobuf +syntax = "proto2"; + message Message { enum MessageType { REGISTER = 0; diff --git a/tls/tls.md b/tls/tls.md index e6ef6a1..e17d664 100644 --- a/tls/tls.md +++ b/tls/tls.md @@ -104,6 +104,8 @@ SignedKey ::= SEQUENCE { The publicKey field of `SignedKey` contains the public host key of the endpoint, encoded using the following protobuf: ```protobuf +syntax = "proto2"; + enum KeyType { RSA = 0; Ed25519 = 1;