libp2p/go-libp2p-core
1
0
Fork 0
mirror of https://github.com/libp2p/go-libp2p-core.git synced 2025-03-22 12:20:07 +08:00
Code Issues Projects Releases Wiki Activity

doc comments

Browse Source
This commit is contained in:
Yusef Napora 2020-01-16 10:32:17 -05:00
parent 8d8da386f2
commit 39d8cbc758
2 changed files with 18 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
peer/record.go
View File

@ -33,8 +33,9 @@ var ErrPeerIdMismatch = errors.New("signing key does not match record.PeerID")
// Currently, a PeerRecord contains the public listen addresses for a peer, but this // Currently, a PeerRecord contains the public listen addresses for a peer, but this
// is expected to expand to include other information in the future. // is expected to expand to include other information in the future.
// //
// PeerRecords are intended to be signed by the peer they describe, and there are no // PeerRecords are intended to be shared with other peers inside a signed
// public methods for marshalling unsigned PeerRecords. // routing.Envelope, and PeerRecord implements the routing.Record interface
// to facilitate this.
// //
// To share a PeerRecord, first call Sign to wrap the record in a Envelope // To share a PeerRecord, first call Sign to wrap the record in a Envelope
// and sign it with the local peer's private key: // and sign it with the local peer's private key:
@ -50,18 +51,16 @@ var ErrPeerIdMismatch = errors.New("signing key does not match record.PeerID")
// recordBytes, err := rec.MarshalSigned(myPrivateKey) // recordBytes, err := rec.MarshalSigned(myPrivateKey)
// //
// To validate and unmarshal a signed PeerRecord from a remote peer, // To validate and unmarshal a signed PeerRecord from a remote peer,
// "consume" the containing envelope and unmarshal the payload using // "consume" the containing envelope, which will return both the
// the Unmarshal method on an empty PeerRecord: // routing.Envelope and the inner Record. The Record must be cast to
// a PeerRecord pointer before use:
// //
// envelope, err := record.ConsumeEnvelope(envelopeBytes, PeerRecordEnvelopeDomain) // envelope, untypedRecord, err := ConsumeEnvelope(envelopeBytes, PeerRecordEnvelopeDomain)
// if err != nil { // if err != nil {
// doSomething(err) // handleError(err)
// return
// } // }
// var rec *PeerRecord // peerRec := untypedRecord.(*PeerRecord)
// err = rec.Unmarshal(envelope.Payload)
//
// You may also want to check that envelope.PayloadType matches PeerRecordEnvelopePayloadType
// before unmarshaling the payload.
// //
type PeerRecord struct { type PeerRecord struct {
// PeerID is the ID of the peer this record pertains to. // PeerID is the ID of the peer this record pertains to.
@ -77,7 +76,10 @@ func PeerRecordFromAddrInfo(info AddrInfo) *PeerRecord {
return &PeerRecord{PeerID: info.ID, Addrs: info.Addrs} return &PeerRecord{PeerID: info.ID, Addrs: info.Addrs}
} }
// TODO(yusef): doc comment // UnmarshalRecord parses a PeerRecord from a byte slice.
// This method is called automatically when consuming a record.Envelope
// whose PayloadType indicates that it contains a PeerRecord.
// It is generally not necessary or recommended to call this method directly.
func (r *PeerRecord) UnmarshalRecord(bytes []byte) error { func (r *PeerRecord) UnmarshalRecord(bytes []byte) error {
if r == nil { if r == nil {
return fmt.Errorf("cannot unmarshal PeerRecord to nil receiver") return fmt.Errorf("cannot unmarshal PeerRecord to nil receiver")
@ -98,7 +100,9 @@ func (r *PeerRecord) UnmarshalRecord(bytes []byte) error {
return nil return nil
} }
// TODO(yusef): doc comment // MarshalRecord serializes a PeerRecord to a byte slice.
// This method is called automatically when constructing a routing.Envelope
// using MakeEnvelopeWithRecord or PeerRecord.Sign.
func (r *PeerRecord) MarshalRecord() ([]byte, error) { func (r *PeerRecord) MarshalRecord() ([]byte, error) {
idBytes, err := r.PeerID.MarshalBinary() idBytes, err := r.PeerID.MarshalBinary()
if err != nil { if err != nil {

2
record/envelope.go
View File

@ -81,7 +81,7 @@ func MakeEnvelope(privateKey crypto.PrivKey, domain string, payloadType []byte,
// MakeEnvelopeWithRecord wraps the given Record in an Envelope, and signs it using the given key // MakeEnvelopeWithRecord wraps the given Record in an Envelope, and signs it using the given key
// and domain string. // and domain string.
// //
// The Record's concrete type must be associated with a multicodec payload type identifier // The Record's concrete type must be associated with a payload type identifier
// (see record.RegisterPayloadType). // (see record.RegisterPayloadType).
func MakeEnvelopeWithRecord(privateKey crypto.PrivKey, domain string, rec Record) (*Envelope, error) { func MakeEnvelopeWithRecord(privateKey crypto.PrivKey, domain string, rec Record) (*Envelope, error) {
payloadType, ok := payloadTypeForRecord(rec) payloadType, ok := payloadTypeForRecord(rec)