network

package
v0.20.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2022 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 3 Imported by: 896

Documentation

Overview

Deprecated: This package has moved into go-libp2p as a sub-package: github.com/libp2p/go-libp2p/core/network.

Package network provides core networking abstractions for libp2p.

The network package provides the high-level Network interface for interacting with other libp2p peers, which is the primary public API for initiating and accepting connections to remote peers.

Index

Constants

View Source 
const (
	// NATDeviceTypeUnknown indicates that the type of the NAT device is unknown.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NATDeviceTypeUnknown instead
	NATDeviceTypeUnknown = network.NATDeviceTypeUnknown

	// NATDeviceTypeCone indicates that the NAT device is a Cone NAT.
	// A Cone NAT is a NAT where all outgoing connections from the same source IP address and port are mapped by the NAT device
	// to the same IP address and port irrespective of the destination address.
	// With regards to RFC 3489, this could be either a Full Cone NAT, a Restricted Cone NAT or a
	// Port Restricted Cone NAT. However, we do NOT differentiate between them here and simply classify all such NATs as a Cone NAT.
	// NAT traversal with hole punching is possible with a Cone NAT ONLY if the remote peer is ALSO behind a Cone NAT.
	// If the remote peer is behind a Symmetric NAT, hole punching will fail.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NATDeviceTypeConn instead
	NATDeviceTypeCone = network.NATDeviceTypeCone

	// NATDeviceTypeSymmetric indicates that the NAT device is a Symmetric NAT.
	// A Symmetric NAT maps outgoing connections with different destination addresses to different IP addresses and ports,
	// even if they originate from the same source IP address and port.
	// NAT traversal with hole-punching is currently NOT possible in libp2p with Symmetric NATs irrespective of the remote peer's NAT type.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NATDeviceTypeSymmetric instead
	NATDeviceTypeSymmetric = network.NATDeviceTypeSymmetric
)
View Source 
const (
	// NATTransportUDP means that the NAT Device Type has been determined for the UDP Protocol.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NATTransportUDP instead
	NATTransportUDP = network.NATTransportUDP
	// NATTransportTCP means that the NAT Device Type has been determined for the TCP Protocol.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NATTransportTCP instead
	NATTransportTCP = network.NATTransportTCP
)
View Source 
const (
	// DirUnknown is the default direction.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.DirUnknown instead
	DirUnknown = network.DirUnknown
	// DirInbound is for when the remote peer initiated a connection.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.DirInbound instead
	DirInbound = network.DirInbound
	// DirOutbound is for when the local peer initiated a connection.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.DirOutbound instead
	DirOutbound = network.DirOutbound
)
View Source 
const (
	// NotConnected means no connection to peer, and no extra information (default)
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.NotConnected instead
	NotConnected = network.NotConnected

	// Connected means has an open, live connection to peer
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.Connected instead
	Connected = network.Connected

	// CanConnect means recently connected to peer, terminated gracefully
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.CanConnect instead
	CanConnect = network.CanConnect

	// CannotConnect means recently attempted connecting but failed to connect.
	// (should signal "made effort, failed")
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.CannotConnect instead
	CannotConnect = network.CannotConnect
)
View Source 
const (
	// ReachabilityUnknown indicates that the reachability status of the
	// node is unknown.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReachabilityUnknown instead
	ReachabilityUnknown = network.ReachabilityUnknown

	// ReachabilityPublic indicates that the node is reachable from the
	// public internet.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReachabilityPubic instead
	ReachabilityPublic = network.ReachabilityPublic

	// ReachabilityPrivate indicates that the node is not reachable from the
	// public internet.
	//
	// NOTE: This node may _still_ be reachable via relays.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReachabilityPrivate instead
	ReachabilityPrivate = network.ReachabilityPrivate
)
View Source 
const (
	// ReservationPriorityLow is a reservation priority that indicates a reservation if the scope
	// memory utilization is at 40% or less.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityLow instead
	ReservationPriorityLow = network.ReservationPriorityLow
	// ReservationPriorityMedium is a reservation priority that indicates a reservation if the scope
	// memory utilization is at 60% or less.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityMedium instead
	ReservationPriorityMedium uint8 = network.ReservationPriorityMedium
	// ReservationPriorityHigh is a reservation prioirity that indicates a reservation if the scope
	// memory utilization is at 80% or less.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityHigh instead
	ReservationPriorityHigh uint8 = network.ReservationPriorityHigh
	// ReservationPriorityAlways is a reservation priority that indicates a reservation if there is
	// enough memory, regardless of scope utilization.
	// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityAlways instead
	ReservationPriorityAlways = network.ReservationPriorityAlways
)
View Source 
const MessageSizeMax = network.MessageSizeMax

MessageSizeMax is a soft (recommended) maximum for network messages. One can write more, as the interface is a stream. But it is useful to bunch it up into multiple read/writes when the whole message is a single, large serialized object. Deprecated: use github.com/libp2p/go-libp2p/core/network.MessageSizeMax instead

Variables

View Source 
var DialPeerTimeout = network.DialPeerTimeout

DialPeerTimeout is the default timeout for a single call to `DialPeer`. When there are multiple concurrent calls to `DialPeer`, this timeout will apply to each independently. Deprecated: use github.com/libp2p/go-libp2p/core/network.DialPeerTimeout instead

View Source 
var ErrNoConn = network.ErrNoConn

ErrNoConn is returned when attempting to open a stream to a peer with the NoDial option and no usable connection is available. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrNoConn instead

View Source 
var ErrNoRemoteAddrs = network.ErrNoRemoteAddrs

ErrNoRemoteAddrs is returned when there are no addresses associated with a peer during a dial. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrNoRemoteAddrs instead

View Source 
var ErrReset = network.ErrReset

ErrReset is returned when reading or writing on a reset stream. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrReset instead

View Source 
var ErrResourceLimitExceeded = network.ErrResourceLimitExceeded

ErrResourceLimitExceeded is returned when attempting to perform an operation that would exceed system resource limits. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrResourceLimitExceeded instead

View Source 
var ErrResourceScopeClosed = network.ErrResourceScopeClosed

ErrResourceScopeClosed is returned when attemptig to reserve resources in a closed resource scope. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrResourceScopeClosed instead

View Source 
var ErrTransientConn = network.ErrTransientConn

ErrTransientConn is returned when attempting to open a stream to a peer with only a transient connection, without specifying the UseTransient option. Deprecated: use github.com/libp2p/go-libp2p/core/network.ErrTransientConn instead

View Source 
var GlobalNoopNotifiee = network.GlobalNoopNotifiee

Global noop notifiee. Do not change. Deprecated: use github.com/libp2p/go-libp2p/core/network.GlobalNoopNotifiee instead

View Source 
var NullResourceManager = network.NullResourceManager

NullResourceManager is a stub for tests and initialization of default values Deprecated: use github.com/libp2p/go-libp2p/core/network.NullResourceManager instead

Functions

func GetDialPeerTimeout 

func GetDialPeerTimeout(ctx context.Context) time.Duration

GetDialPeerTimeout returns the current DialPeer timeout (or the default). Deprecated: use github.com/libp2p/go-libp2p/core/network.GetDialPeerTimeout instead

func GetForceDirectDial added in v0.7.1 

func GetForceDirectDial(ctx context.Context) (forceDirect bool, reason string)

EXPERIMENTAL GetForceDirectDial returns true if the force direct dial option is set in the context. Deprecated: use github.com/libp2p/go-libp2p/core/network.GetForceDirectDial instead

func GetNoDial 

func GetNoDial(ctx context.Context) (nodial bool, reason string)

GetNoDial returns true if the no dial option is set in the context. Deprecated: use github.com/libp2p/go-libp2p/core/network.GetNoDial instead

func GetSimultaneousConnect added in v0.8.5 

func GetSimultaneousConnect(ctx context.Context) (simconnect bool, isClient bool, reason string)

GetSimultaneousConnect returns true if the simultaneous connect option is set in the context. EXPERIMENTAL Deprecated: use github.com/libp2p/go-libp2p/core/network.GetSimultaneousConnect instead

func GetUseTransient added in v0.8.2 

func GetUseTransient(ctx context.Context) (usetransient bool, reason string)

GetUseTransient returns true if the use transient option is set in the context. Deprecated: use github.com/libp2p/go-libp2p/core/network.GetUseTransient instead

func WithDialPeerTimeout 

func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context

WithDialPeerTimeout returns a new context with the DialPeer timeout applied.

This timeout overrides the default DialPeerTimeout and applies per-dial independently. Deprecated: use github.com/libp2p/go-libp2p/core/network.WithDialPeerTimeout instead

func WithForceDirectDial added in v0.7.1 

func WithForceDirectDial(ctx context.Context, reason string) context.Context

EXPERIMENTAL WithForceDirectDial constructs a new context with an option that instructs the network to attempt to force a direct connection to a peer via a dial even if a proxied connection to it already exists. Deprecated: use github.com/libp2p/go-libp2p/core/network.WithForceDirectDial instead

func WithNoDial 

func WithNoDial(ctx context.Context, reason string) context.Context

WithNoDial constructs a new context with an option that instructs the network to not attempt a new dial when opening a stream. Deprecated: use github.com/libp2p/go-libp2p/core/network.WithNoDial instead

func WithSimultaneousConnect added in v0.8.5 

func WithSimultaneousConnect(ctx context.Context, isClient bool, reason string) context.Context

WithSimultaneousConnect constructs a new context with an option that instructs the transport to apply hole punching logic where applicable. EXPERIMENTAL Deprecated: use github.com/libp2p/go-libp2p/core/network.WithSimultaneousConnect instead

func WithUseTransient added in v0.8.2 

func WithUseTransient(ctx context.Context, reason string) context.Context

WithUseTransient constructs a new context with an option that instructs the network that it is acceptable to use a transient connection when opening a new stream. Deprecated: use github.com/libp2p/go-libp2p/core/network.WithUseTransient instead

Types

type Conn deprecated 

type Conn = network.Conn

Conn is a connection to a remote peer. It multiplexes streams. Usually there is no need to use a Conn directly, but it may be useful to get information about the peer on the other side: 

stream.Conn().RemotePeer()

Deprecated: use github.com/libp2p/go-libp2p/core/network.Conn instead

type ConnManagementScope added in v0.14.0 

type ConnManagementScope = network.ConnManagementScope

ConnManagementScope is the low level interface for connection resource scopes. This interface is used by the low level components of the system who create and own the span of a connection scope. Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnManagementScope instead

type ConnMultiaddrs 

type ConnMultiaddrs = network.ConnMultiaddrs

ConnMultiaddrs is an interface mixin for connection types that provide multiaddr addresses for the endpoints. Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnMultiaddrs instead

type ConnScope added in v0.14.0 

type ConnScope = network.ConnScope

ConnScope is the user view of a connection scope Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnScope instead

type ConnScoper added in v0.14.0 

type ConnScoper = network.ConnScoper

ConnScoper is the interface that one can mix into a connection interface to give it a resource management scope Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnScoper instead

type ConnSecurity 

type ConnSecurity = network.ConnSecurity

ConnSecurity is the interface that one can mix into a connection interface to give it the security methods. Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnSecurity instead

type ConnStat added in v0.8.2 

type ConnStat = network.ConnStats

ConnStat is an interface mixin for connection types that provide connection statistics. Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnStat instead

type ConnStats added in v0.13.0 

type ConnStats = network.ConnStats

ConnStats stores metadata pertaining to a given Conn. Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnStats instead

type Connectedness 

type Connectedness = network.Connectedness

Connectedness signals the capacity for a connection with a given node. It is used to signal to services and other peers whether a node is reachable.

type Dialer 

type Dialer = network.Dialer

Dialer represents a service that can dial out to peers (this is usually just a Network, but other services may not need the whole stack, and thus it becomes easier to mock) Deprecated: use github.com/libp2p/go-libp2p/core/network.Dialer instead

type Direction 

type Direction = network.Direction

Direction represents which peer in a stream initiated a connection. Deprecated: use github.com/libp2p/go-libp2p/core/network.Direction instead

type Multiplexer added in v0.14.0 

type Multiplexer = network.Multiplexer

Multiplexer wraps a net.Conn with a stream multiplexing implementation and returns a MuxedConn that supports opening multiple streams over the underlying net.Conn Deprecated: use github.com/libp2p/go-libp2p/core/network.Multiplexer instead

type MuxedConn added in v0.14.0 

type MuxedConn = network.MuxedConn

MuxedConn represents a connection to a remote peer that has been extended to support stream multiplexing.

A MuxedConn allows a single net.Conn connection to carry many logically independent bidirectional streams of binary data.

Together with network.ConnSecurity, MuxedConn is a component of the transport.CapableConn interface, which represents a "raw" network connection that has been "upgraded" to support the libp2p capabilities of secure communication and stream multiplexing. Deprecated: use github.com/libp2p/go-libp2p/core/network.MuxedConn instead

type MuxedStream added in v0.14.0 

type MuxedStream = network.MuxedStream

MuxedStream is a bidirectional io pipe within a connection. Deprecated: use github.com/libp2p/go-libp2p/core/network.MuxedStream instead

type NATDeviceType added in v0.8.4 

type NATDeviceType = network.NATDeviceType

NATDeviceType indicates the type of the NAT device. Deprecated: use github.com/libp2p/go-libp2p/core/network.NATDeviceType instead

type NATTransportProtocol added in v0.8.4 

type NATTransportProtocol = network.NATTransportProtocol

NATTransportProtocol is the transport protocol for which the NAT Device Type has been determined. Deprecated: use github.com/libp2p/go-libp2p/core/network.NATTransportProtocol instead

type Network 

type Network = network.Network

Network is the interface used to connect to the outside world. It dials and listens for connections. it uses a Swarm to pool connections (see swarm pkg, and peerstream.Swarm). Connections are encrypted with a TLS-like protocol. Deprecated: use github.com/libp2p/go-libp2p/core/network.Network instead

type NoopNotifiee deprecated 

type NoopNotifiee = network.NoopNotifiee

Deprecated: use github.com/libp2p/go-libp2p/core/network.NoopNotifiee instead

type Notifiee 

type Notifiee = network.Notifiee

Notifiee is an interface for an object wishing to receive notifications from a Network. Deprecated: use github.com/libp2p/go-libp2p/core/network.Notifiee instead

type NotifyBundle 

type NotifyBundle = network.NotifyBundle

NotifyBundle implements Notifiee by calling any of the functions set on it, and nop'ing if they are unset. This is the easy way to register for notifications. Deprecated: use github.com/libp2p/go-libp2p/core/network.NotifyBundle instead

type PeerScope added in v0.14.0 

type PeerScope = network.PeerScope

PeerScope is the interface for peer resource scopes. Deprecated: use github.com/libp2p/go-libp2p/core/network.PeerScope instead

type ProtocolScope added in v0.14.0 

type ProtocolScope = network.ProtocolScope

ProtocolScope is the interface for protocol resource scopes. Deprecated: use github.com/libp2p/go-libp2p/core/network.ProtocolScope instead

type Reachability added in v0.4.0 

type Reachability = network.Reachability

Reachability indicates how reachable a node is. Deprecated: use github.com/libp2p/go-libp2p/core/network.Reachability instead

type ResourceManager deprecated added in v0.14.0 

type ResourceManager = network.ResourceManager

ResourceManager is the interface to the network resource management subsystem. The ResourceManager tracks and accounts for resource usage in the stack, from the internals to the application, and provides a mechanism to limit resource usage according to a user configurable policy.

Resource Management through the ResourceManager is based on the concept of Resource Management Scopes, whereby resource usage is constrained by a DAG of scopes, The following diagram illustrates the structure of the resource constraint DAG: System 

+------------> Transient.............+................+
|                                    .                .
+------------>  Service------------- . ----------+    .
|                                    .           |    .
+------------->  Protocol----------- . ----------+    .
|                                    .           |    .
+-------------->  Peer               \           |    .
                   +------------> Connection     |    .
                   |                             \    \
                   +--------------------------->  Stream

The basic resources accounted by the ResourceManager include memory, streams, connections, and file descriptors. These account for both space and time used by the stack, as each resource has a direct effect on the system availability and performance.

The modus operandi of the resource manager is to restrict resource usage at the time of reservation. When a component of the stack needs to use a resource, it reserves it in the appropriate scope. The resource manager gates the reservation against the scope applicable limits; if the limit is exceeded, then an error (wrapping ErrResourceLimitExceeded) and it is up the component to act accordingly. At the lower levels of the stack, this will normally signal a failure of some sorts, like failing to opening a stream or a connection, which will propagate to the programmer. Some components may be able to handle resource reservation failure more gracefully; for instance a muxer trying to grow a buffer for a window change, will simply retain the existing window size and continue to operate normally albeit with some degraded throughput. All resources reserved in some scope are released when the scope is closed. For low level scopes, mainly Connection and Stream scopes, this happens when the connection or stream is closed.

Service programmers will typically use the resource manager to reserve memory for their subsystem. This happens with two avenues: the programmer can attach a stream to a service, whereby resources reserved by the stream are automatically accounted in the service budget; or the programmer may directly interact with the service scope, by using ViewService through the resource manager interface.

Application programmers can also directly reserve memory in some applicable scope. In order to facilitate control flow delimited resource accounting, all scopes defined in the system allow for the user to create spans. Spans are temporary scopes rooted at some other scope and release their resources when the programmer is done with them. Span scopes can form trees, with nested spans.

Typical Usage:

  • Low level components of the system (transports, muxers) all have access to the resource manager and create connection and stream scopes through it. These scopes are accessible to the user, albeit with a narrower interface, through Conn and Stream objects who have a Scope method.
  • Services typically center around streams, where the programmer can attach streams to a particular service. They can also directly reserve memory for a service by accessing the service scope using the ResourceManager interface.
  • Applications that want to account for their network resource usage can reserve memory, typically using a span, directly in the System or a Service scope; they can also opt to use appropriate steam scopes for streams that they create or own.

User Serviceable Parts: the user has the option to specify their own implementation of the interface. We provide a canonical implementation in the go-libp2p-resource-manager package. The user of that package can specify limits for the various scopes, which can be static or dynamic.

WARNING The ResourceManager interface is considered experimental and subject to change 

in subsequent releases.

Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceManager instead

type ResourceScope added in v0.14.0 

type ResourceScope = network.ResourceScope

ResourceScope is the interface for all scopes. Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScope instead

type ResourceScopeSpan deprecated added in v0.14.0 

type ResourceScopeSpan = network.ResourceScopeSpan

ResourceScopeSpan is a ResourceScope with a delimited span. Span scopes are control flow delimited and release all their associated resources when the programmer calls Done.

Example: 

s, err := someScope.BeginSpan()
if err != nil { ... }
defer s.Done()

if err := s.ReserveMemory(...); err != nil { ... }
// ... use memory

Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScopeSpan instead

type ResourceScopeViewer added in v0.14.0 

type ResourceScopeViewer = network.ResourceScopeViewer

ResourceScopeViewer is a mixin interface providing view methods for accessing top level scopes. Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScopeViewer instead

type ScopeStat added in v0.14.0 

type ScopeStat = network.ScopeStat

ScopeStat is a struct containing resource accounting information. Deprecated: use github.com/libp2p/go-libp2p/core/network.ScopeStat instead

type ServiceScope added in v0.14.0 

type ServiceScope = network.ServiceScope

ServiceScope is the interface for service resource scopes Deprecated: use github.com/libp2p/go-libp2p/core/network.ServiceScope instead

type Stats added in v0.13.0 

type Stats = network.Stats

Stats stores metadata pertaining to a given Stream / Conn. Deprecated: use github.com/libp2p/go-libp2p/core/network.Stats instead

type Stream 

type Stream = network.Stream

Stream represents a bidirectional channel between two agents in a libp2p network. "agent" is as granular as desired, potentially being a "request -> reply" pair, or whole protocols.

Streams are backed by a multiplexer underneath the hood. Deprecated: use github.com/libp2p/go-libp2p/core/network.Stream instead

type StreamHandler 

type StreamHandler = network.StreamHandler

StreamHandler is the type of function used to listen for streams opened by the remote side. Deprecated: use github.com/libp2p/go-libp2p/core/network.StreamHandler instead

type StreamManagementScope added in v0.14.0 

type StreamManagementScope = network.StreamManagementScope

StreamManagementScope is the interface for stream resource scopes. This interface is used by the low level components of the system who create and own the span of a stream scope. Deprecated: use github.com/libp2p/go-libp2p/core/network.StreamManagementScope instead

type StreamScope added in v0.14.0 

type StreamScope = network.StreamScope

StreamScope is the user view of a StreamScope. Deprecated: use github.com/libp2p/go-libp2p/core/network.StreamScope instead

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.