-
Notifications
You must be signed in to change notification settings - Fork 273
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
identify spec #97
identify spec #97
Changes from 4 commits
723e6f3
bbc2d58
e665138
da8bd9c
71ff29c
749fc10
a1daad7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
# Identify v1.0.0 | ||
|
||
The identify protocol is used to identify a peer and its capabilities. | ||
|
||
The protocol works by opening a stream, using `/ipfs/id/1.0.0` as the protocol string. | ||
The peer being identified responds by returning an `Identify` message and closes the | ||
stream. | ||
|
||
## The Identify Message | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should probably note that any missing fields should be ignored (so we can do a partial identify push). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @yusefnapora want to add it? |
||
|
||
```protobuf | ||
message Identify { | ||
optional string protocolVersion = 5; | ||
optional string agentVersion = 6; | ||
optional bytes publicKey = 1; | ||
repeated bytes listenAddrs = 2; | ||
optional bytes observedAddr = 4; | ||
repeated string protocols = 3; | ||
} | ||
``` | ||
|
||
### protocolVersion | ||
|
||
The protocol version identifies the family of protocols used by the peer. | ||
The current protocol version is `ipfs/0.1.0`; if the protocol major or minor | ||
version does not match the protocol used by the initiating peer, then the connection | ||
is considered unusable and the peer must close the connection. | ||
|
||
### agentVersion | ||
|
||
This is a free-form string, identifying the implementation of the peer. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. can we encourage a particular format, even if non-normative? the default is https://github.com/ipfs/go-ipfs/blob/master/core/core.go#L99 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nah, let's let people call their agents whatever they want! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. although an example might be useful. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. example sounds good |
||
The usual format is `agent-name/version`, where `agent-name` is | ||
the name of the program or library and `version` is its semantic version. | ||
|
||
### publicKey | ||
|
||
This is the public key of the peer, marshalled in binary form as specicfied | ||
in [peer-ids](../peer-ids). | ||
|
||
|
||
### listenAddrs | ||
|
||
These are the addresses on which the peer is listening as multi-addresses. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Does the multiaddress also include There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It doesn't include it. Well, it shouldn't. |
||
### observedAddr | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There are two possibilities here: this can be either the stack of protocols the listener used in order to reach back the dialer, or the stack of protocols we think the dialer used to reach us. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added a There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Per discussion I'm not satisfied with the wording, because I'd like to disambiguate what is returned when There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We can add an example for circuit addresses specifically, as they seem to be the contentious issue. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added some examples, hopefully it's clearer now. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. maybe something like: "This address describes the dialed peer's observed route to the dialing peer." so wordy tho There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yeah, and it's not really any better than the current wording. |
||
|
||
This is the connection source address of the stream initiating peer as observed by the peer | ||
being identified; it is a multi-address. The initiator can use this address to infer | ||
the existence of a NAT and its public address. | ||
|
||
For example, in the case of a TCP/IP transport the observed addresses will be of the form | ||
`/ip4/x.x.x.x/tcp/xx`. In the case of a circuit relay connection, the observed address will | ||
be of the form `/p2p/QmRelay/p2p-circuit`. In the case of onion transport, there is no | ||
observable source address. | ||
|
||
### protocols | ||
|
||
This is a list of protocols supported by the peer. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. not ordered in any specific manner. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. right, but do we need to say that? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. A list implies order. If order is not important, then we can say it's an unordered set. We shouldn't be sending duplicates anyway, right? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. it's a list on the wire, there is no set datatype. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. might be worth clarifying that this are multistream protocols (or protocol strings)? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can we unpack the definition of "identify a peer"? the recursive definition is confusing for a spec
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
uhm ok; me loves recursion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i really can't think of a non-verbose way of expressing this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about "the identify protocol is used to interrogate a peer for basic information and its capabilities, the details of which are defined below"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
query, not interrogate.