yggdrasil-network/yggdrasil-go
1
0
Fork 0
mirror of https://github.com/yggdrasil-network/yggdrasil-go.git synced 2025-11-04 11:15:07 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation updates

Browse source
This commit is contained in:
Neil Alexander 2019-09-01 23:10:46 +01:00
parent 01517e5dc3
commit 9e8e1c5a41
No known key found for this signature in database
GPG key ID: A02A2019A2BB0944
2 changed files with 68 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

84
src/yggdrasil/api.go
View file

@ -16,29 +16,37 @@ import (
) )
// Peer represents a single peer object. This contains information from the // Peer represents a single peer object. This contains information from the
// preferred switch port for this peer, although there may be more than one in // preferred switch port for this peer, although there may be more than one
// reality. // active switch port connection to the peer in reality.
//
// This struct is informational only - you cannot manipulate peer connections
// using instances of this struct. You should use the AddPeer or RemovePeer
// functions instead.
type Peer struct { type Peer struct {
PublicKey crypto.BoxPubKey PublicKey crypto.BoxPubKey // The public key of the remote node
Endpoint string Endpoint string // The connection string used to connect to the peer
BytesSent uint64 BytesSent uint64 // Number of bytes sent to this peer
BytesRecvd uint64 BytesRecvd uint64 // Number of bytes received from this peer
Protocol string Protocol string // The transport protocol that this peer is connected with, typically "tcp"
Port uint64 Port uint64 // Switch port number for this peer connection
Uptime time.Duration Uptime time.Duration // How long this peering has been active for
} }
// SwitchPeer represents a switch connection to a peer. Note that there may be // SwitchPeer represents a switch connection to a peer. Note that there may be
// multiple switch peers per actual peer, e.g. if there are multiple connections // multiple switch peers per actual peer, e.g. if there are multiple connections
// to a given node. // to a given node.
//
// This struct is informational only - you cannot manipulate switch peer
// connections using instances of this struct. You should use the AddPeer or
// RemovePeer functions instead.
type SwitchPeer struct { type SwitchPeer struct {
PublicKey crypto.BoxPubKey PublicKey crypto.BoxPubKey // The public key of the remote node
Coords []uint64 Coords []uint64 // The coordinates of the remote node
BytesSent uint64 BytesSent uint64 // Number of bytes sent via this switch port
BytesRecvd uint64 BytesRecvd uint64 // Number of bytes received via this switch port
Port uint64 Port uint64 // Switch port number for this switch peer
Protocol string Protocol string // The transport protocol that this switch port is connected with, typically "tcp"
Endpoint string Endpoint string // The connection string used to connect to the switch peer
} }
// DHTEntry represents a single DHT entry that has been learned or cached from // DHTEntry represents a single DHT entry that has been learned or cached from
@ -64,32 +72,36 @@ type NodeInfoPayload []byte
// congestion and a list of switch queues created in response to congestion on a // congestion and a list of switch queues created in response to congestion on a
// given link. // given link.
type SwitchQueues struct { type SwitchQueues struct {
Queues []SwitchQueue Queues []SwitchQueue // An array of SwitchQueue objects containing information about individual queues
Count uint64 Count uint64 // The current number of active switch queues
Size uint64 Size uint64 // The current total size of active switch queues
HighestCount uint64 HighestCount uint64 // The highest recorded number of switch queues so far
HighestSize uint64 HighestSize uint64 // The highest recorded total size of switch queues so far
MaximumSize uint64 MaximumSize uint64 // The maximum allowed total size of switch queues, as specified by config
} }
// SwitchQueue represents a single switch queue, which is created in response // SwitchQueue represents a single switch queue. Switch queues are only created
// to congestion on a given link. // in response to congestion on a given link and represent how much data has
// been temporarily cached for sending once the congestion has cleared.
type SwitchQueue struct { type SwitchQueue struct {
ID string ID string // The ID of the switch queue
Size uint64 Size uint64 // The total size, in bytes, of the queue
Packets uint64 Packets uint64 // The number of packets in the queue
Port uint64 Port uint64 // The switch port to which the queue applies
} }
// Session represents an open session with another node. // Session represents an open session with another node. Sessions are opened in
// response to traffic being exchanged between two nodes using Conn objects.
// Note that sessions will automatically be closed by Yggdrasil if no traffic is
// exchanged for around two minutes.
type Session struct { type Session struct {
PublicKey crypto.BoxPubKey PublicKey crypto.BoxPubKey // The public key of the remote node
Coords []uint64 Coords []uint64 // The coordinates of the remote node
BytesSent uint64 BytesSent uint64 // Bytes sent to the session
BytesRecvd uint64 BytesRecvd uint64 // Bytes received from the session
MTU uint16 MTU uint16 // The maximum supported message size of the session
Uptime time.Duration Uptime time.Duration // How long this session has been active for
WasMTUFixed bool WasMTUFixed bool // This field is no longer used
} }
// GetPeers returns one or more Peer objects containing information about active // GetPeers returns one or more Peer objects containing information about active

20
src/yggdrasil/doc.go
View file

@ -125,6 +125,9 @@ Using Connections
Conn objects are implementations of io.ReadWriteCloser, and as such, you can Conn objects are implementations of io.ReadWriteCloser, and as such, you can
Read, Write and Close them as necessary. Read, Write and Close them as necessary.
Each Read or Write operation can deal with a buffer with a maximum size of 65535
bytes - any bigger than this and the operation will return an error.
For example, to write to the Conn from the supplied buffer: For example, to write to the Conn from the supplied buffer:
buf := []byte{1, 2, 3, 4, 5} buf := []byte{1, 2, 3, 4, 5}
@ -152,5 +155,22 @@ When you are happy that a connection is no longer required, you can discard it:
// ... // ...
} }
Limitations
You should be aware of the following limitations when working with the Yggdrasil
library:
Individual messages written through Yggdrasil connections can not exceed 65535
bytes in size. Yggdrasil has no concept of fragmentation, so if you try to send
a message that exceeds 65535 bytes in size, it will be dropped altogether and
an error will be returned.
Yggdrasil connections are unreliable by nature. Messages are delivered on a
best-effort basis, and employs congestion control where appropriate to ensure
that congestion does not affect message transport, but Yggdrasil will not
retransmit any messages that have been lost. If reliable delivery is important
then you should manually implement acknowledgement and retransmission of
messages.
*/ */
package yggdrasil package yggdrasil