feat: add peerstore spec and protobuf

pb/p2pd.proto

@@ -13,6 +13,7 @@ message Request {
     CONNMANAGER    = 6;
     DISCONNECT     = 7;
     PUBSUB         = 8;
+    PEERSTORE      = 9;
   }
 
   required Type type = 1;
@@ -24,6 +25,7 @@ message Request {
   optional ConnManagerRequest connManager = 6;
   optional DisconnectRequest disconnect = 7;
   optional PSRequest pubsub = 8;
+  optional PeerstoreRequest peerStore = 9;
 }
 
 message Response {
@@ -39,6 +41,7 @@ message Response {
   optional DHTResponse dht = 5;
   repeated PeerInfo peers = 6;
   optional PSResponse pubsub = 7;
+  optional PeerstoreResponse peerStore = 8;
 }
 
 message IdentifyResponse {
@@ -155,4 +158,42 @@ message PSMessage {
 message PSResponse {
   repeated string topics = 1;
   repeated bytes peerIDs = 2;
-}
+}
+
+message PeerstoreRequest {
+  enum Type {
+    GET_PROTOCOLS = 1;
+    GET_PEER_INFO = 2;
+    GET_PEER_INFOS = 3;
+    GET_PEERS = 4;
+    ADD_ADDRS = 5;
+    SET_ADDRS = 6;
+    UPDATE_ADDRS = 7;
+    ADDRS = 8;
+    ADDR_STREAM = 9;
+    CLEAR_ADDRS = 10;
+    PEERS_WITH_ADDRS = 11;
+    PUB_KEY = 12;
+    ADD_PUB_KEY = 13;
+    PRIV_KEY = 14;
+    ADD_PRIV_KEY = 15;
+    PEERS_WITH_KEYS = 16;
+    RECORD_LATENCY = 17;
+    GET_LATENCY = 18;
+  }
+
+  required Type type = 1;
+  optional bytes id = 2;
+  repeated string protos = 3;
+  repeated bytes addrs = 4;
+  optional int64 nextTime = 5;
+  optional int64 oldTime = 6;
+}
+
+message PeerstoreResponse {
+  optional PeerInfo peer = 1;
+  repeated string protos = 2;
+  repeated bytes peerIDs = 3;
+  repeated PeerInfo peers = 4;
+  optional int64 time = 5;
+}

specs/PEERSTORE.md

@@ -0,0 +1,120 @@
+# libp2p Daemon Peerstore Protocol
+
+The libp2p daemon Peerstore protocol allows clients to interact with the libp2p daemon's Peerstore.
+
+_At the moment, this is a living document. As such, it will be susceptible to
+changes until stabilization._
+
+## Protocol Specification
+
+### Data Types
+
+The data structures are defined in [pb/p2pd.proto](../pb/p2pd.proto). All messages
+are varint-delimited. For the DHT queries, the relevant data types are:
+
+- `PeerstoreRequest`
+- `PeerstoreResponse`
+
+All Peerstore requests will be wrapped in a `Request` message with `Type: PEERSTORE`.
+Peerstore responses from the daemon will be wrapped in a `Response` with the
+`PeerstoreResponse` field populated. Some responses will be basic `Response` messages to convey whether or not there was an error.
+
+`PeerstoreRequest` messages have a `Type` parameter that specifies the specific operation
+the client wishes to execute.
+
+### Protocol Requests
+
+*Protocols described in pseudo-go. Items of the form [item, ...] are lists of
+many items.*
+
+#### Errors
+
+Any response that may be an error, will take the form of:
+
+```
+Response{
+  Type: ERROR,
+  ErrorResponse: {
+    Msg: <error message>,
+  },
+}
+```
+
+#### `ADD_PROTOCOLS`
+Clients can issue a `ADD_PROTOCOLS` request to add protocols to the known list for a given peer.
+
+**Client**
+```
+Request{
+  Type: PEERSTORE,
+  PeerstoreRequest: PeerstoreRequest{
+    Type: ADD_PROTOCOLS,
+    Id: <peer id>,
+    Protos: [<protocol string>, ...],
+  },
+}
+```
+
+**Daemon**
+*Can return an error*
+
+```
+Response{
+  Type: OK
+}
+```
+
+#### `GET_PROTOCOLS`
+Clients can issue a `GET_PROTOCOLS` request to get the known list of protocols for a given peer.
+
+**Client**
+```
+Request{
+  Type: PEERSTORE,
+  PeerstoreRequest: PeerstoreRequest{
+    Type: GET_PROTOCOLS,
+    Id: <peer id>,
+  },
+}
+```
+
+**Daemon**
+*Can return an error*
+
+```
+Response{
+  Type: OK,
+  PeerstoreResponse: PeerstoreResponse{
+    Protos: [<protocol string>, ...],
+  },
+}
+```
+
+#### `GET_PEER_INFO`
+Clients can issue a `GET_PEER_INFO` request to get the PeerInfo for a given peer id.
+
+**Client**
+```
+Request{
+  Type: PEERSTORE,
+  PeerstoreRequest: PeerstoreRequest{
+    Type: GET_PEER_INFO,
+    Id: <peer id>,
+  },
+}
+```
+
+**Daemon**
+*Can return an error*
+
+```
+Response{
+  Type: OK,
+  PeerstoreResponse: PeerstoreResponse{
+    Peer: PeerInfo{
+      Id: <peer id>,
+      Addrs: [<addr>, ...],
+    },
+  },
+}
+```

specs/README.md

@@ -6,3 +6,5 @@ The daemon specs are broken into a few main pieces:
   adding peers, connecting to them, and opening streams.
 - The [DHT subsystem](DHT.md): Governs DHT client operations.
 - The [Connection Manager](CM.md): Governs the connection manager API.
+- The [Peerstore](PEERSTORE.md): Governs Peerstore operations.
+- The [PubSub subsystem](PUBSUB.md): Governs PubSub operations.