Skip to content
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

Merged
merged 7 commits into from May 1, 2019
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
@@ -0,0 +1,84 @@
# Identify v1.0.0

The identify protocol is used to exchange basic information with other peers
in the network, including addresses, public keys, and capabilities.

There are two variations of the identify protocol, `identify` and `identify/push`.

### `identify`

The `identify` protocol has the protocol id `/ipfs/id/1.0.0`, and it is used
to query remote peers for their information.

The protocol works by opening a stream to the remote peer you want to query, using
`/ipfs/id/1.0.0` as the protocol id string. The peer being identified responds by returning
an `Identify` message and closes the stream.

### `identify/push`

The `identify/push` protocol has the protocol id `/ipfs/id/push/1.0.0`, and it is used
to inform known peers about changes that occur at runtime.

When a peer's basic information changes, for example, because they've obtained a new
public listen address, they can use `identify/push` to inform others about the new
information.

The push variant works by opening a stream to each remote peer you want to update, using
`/ipfs/id/push/1.0.0` as the protocol id string. When the remote peer accepts the stream,
the local peer will send an `Identify` message and close the stream.

Upon recieving the pushed `Identify` message, the remote peer should update their local
metadata repository with the information from the message. Note that missing fields
should be ignored, as peers may choose to send partial updates containing only the fields
whose values have changed.

## The Identify Message

This comment has been minimized.

Loading
@Stebalien

Stebalien May 1, 2019
Member

We should probably note that any missing fields should be ignored (so we can do a partial identify push).

This comment has been minimized.

Loading
@vyzo

vyzo May 1, 2019
Author Contributor

@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.

This comment has been minimized.

Loading
@raulk

raulk Oct 11, 2018
Member

can we encourage a particular format, even if non-normative? the default is go-libp2p/<semver>, and IPFS changes this to "go-ipfs/" + version.CurrentVersionNumber + "/" + version.CurrentCommit.

https://github.com/ipfs/go-ipfs/blob/master/core/core.go#L99

This comment has been minimized.

Loading
@vyzo

vyzo Oct 11, 2018
Author Contributor

nah, let's let people call their agents whatever they want!

This comment has been minimized.

Loading
@vyzo

vyzo Oct 11, 2018
Author Contributor

although an example might be useful.

This comment has been minimized.

Loading
@raulk

raulk Oct 11, 2018
Member

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.

This comment has been minimized.

Loading
@richardschneider

richardschneider Nov 9, 2018
Contributor

Does the multiaddress also include /ipfs/Qm...? If so, is /p2p also supported?

This comment has been minimized.

Loading
@Stebalien

Stebalien Nov 9, 2018
Member

It doesn't include it. Well, it shouldn't.

### observedAddr

This comment has been minimized.

Loading
@tomaka

tomaka Oct 10, 2018
Member

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.
For the sake of forward compatibility, I think it'd be a nice idea to define this more precisely, and I'd be in favour of the former.

This comment has been minimized.

Loading
@vyzo

vyzo Oct 10, 2018
Author Contributor

Added a source disambiguator, per discussion in meatspace.

This comment has been minimized.

Loading
@tomaka

tomaka Oct 10, 2018
Member

Per discussion I'm not satisfied with the wording, because I'd like to disambiguate what is returned when p2p-circuit is used, but I can't find any appropriate wording.

This comment has been minimized.

Loading
@vyzo

vyzo Oct 10, 2018
Author Contributor

We can add an example for circuit addresses specifically, as they seem to be the contentious issue.

This comment has been minimized.

Loading
@vyzo

vyzo Oct 10, 2018
Author Contributor

Added some examples, hopefully it's clearer now.

This comment has been minimized.

Loading
@bigs

bigs Oct 12, 2018
Contributor

maybe something like: "This address describes the dialed peer's observed route to the dialing peer."

so wordy tho

This comment has been minimized.

Loading
@vyzo

vyzo Oct 12, 2018
Author Contributor

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.

This comment has been minimized.

Loading
@raulk

raulk Oct 11, 2018
Member

not ordered in any specific manner.

This comment has been minimized.

Loading
@vyzo

vyzo Oct 11, 2018
Author Contributor

right, but do we need to say that?

This comment has been minimized.

Loading
@raulk

raulk Oct 11, 2018
Member

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?

This comment has been minimized.

Loading
@vyzo

vyzo Oct 12, 2018
Author Contributor

it's a list on the wire, there is no set datatype.

This comment has been minimized.

Loading
@dryajov

dryajov Oct 13, 2018
Member

might be worth clarifying that this are multistream protocols (or protocol strings)?