network

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jan 23, 2025 License: MIT Imports: 10 Imported by: 11

Documentation

Overview

Package network 提供了dep2p的核心网络抽象层。

network包提供了与其他dep2p节点交互的高级Network接口,这是用于发起和接受远程节点连接的主要公共API。

Index

Constants

View Source 
const (
	// ReservationPriorityLow 是一个预留优先级,表示范围内存使用率在40%或以下时的预留。
	ReservationPriorityLow uint8 = 101
	// ReservationPriorityMedium 是一个预留优先级,表示范围内存使用率在60%或以下时的预留。
	ReservationPriorityMedium uint8 = 152
	// ReservationPriorityHigh 是一个预留优先级,表示范围内存使用率在80%或以下时的预留。
	ReservationPriorityHigh uint8 = 203
	// ReservationPriorityAlways 是一个预留优先级,表示只要有足够的内存就进行预留,不考虑范围使用率。
	ReservationPriorityAlways uint8 = 255
)
View Source 
const MessageSizeMax = 1 << 22 // 4 MB

MessageSizeMax 是网络消息的软限制(建议)最大值。 由于接口是流式的,可以写入更多数据。 但当整个消息是单个大的序列化对象时,建议将其分成多个读/写操作。

Variables

View Source 
var DialPeerTimeout = 60 * time.Second

DialPeerTimeout 是单个 `DialPeer` 调用的默认超时时间。 当有多个并发的 `DialPeer` 调用时,此超时时间将独立应用于每个调用。

View Source 
var ErrLimitedConn = errors.New("对等节点连接受限")

ErrLimitedConn 当尝试打开到只有有限连接的对等节点的流,但未指定AllowLimitedConn选项时返回此错误

View Source 
var ErrNoConn = errors.New("没有可用的对等节点连接")

ErrNoConn 当使用NoDial选项尝试打开到对等节点的流但没有可用连接时返回此错误

View Source 
var ErrNoRemoteAddrs = errors.New("没有远程地址")

ErrNoRemoteAddrs 当尝试拨号连接对等节点但没有可用地址时返回此错误

View Source 
var ErrReset = errors.New("stream reset")

ErrReset 在读取或写入已重置的流时返回。

View Source 
var ErrResourceLimitExceeded = temporaryError("超出资源限制")

ErrResourceLimitExceeded 当尝试执行的操作会超出系统资源限制时返回此错误

View Source 
var ErrResourceScopeClosed = errors.New("资源作用域已关闭")

ErrResourceScopeClosed 当尝试在已关闭的资源作用域中保留资源时返回此错误

View Source 
var ErrTransientConn = ErrLimitedConn

ErrTransientConn 当尝试打开到只有临时连接的对等节点的流,但未指定UseTransient选项时返回此错误

已弃用: 请使用ErrLimitedConn替代

View Source 
var GlobalNoopNotifiee = &NoopNotifiee{}

GlobalNoopNotifiee 是一个全局的空操作通知接收者。请勿修改。

Functions

func GetAllowLimitedConn 

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

GetAllowLimitedConn 返回上下文中是否设置了允许受限连接选项。 参数:

  • ctx: 要检查的上下文

返回:

  • usetransient: 是否允许受限连接
  • reason: 允许受限连接的原因

func GetDialPeerTimeout 

func GetDialPeerTimeout(ctx context.Context) time.Duration

GetDialPeerTimeout 返回当前的 DialPeer 超时时间(或默认值)。 参数:

  • ctx: 要检查的上下文

返回:

  • time.Duration: 拨号超时时间

func GetForceDirectDial 

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

EXPERIMENTAL GetForceDirectDial 返回上下文中是否设置了强制直接拨号选项。 参数:

  • ctx: 要检查的上下文

返回:

  • forceDirect: 是否设置了强制直接拨号
  • reason: 设置强制直接拨号的原因

func GetNoDial 

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

GetNoDial 返回上下文中是否设置了禁用拨号选项。 参数:

  • ctx: 要检查的上下文

返回:

  • nodial: 是否禁用拨号
  • reason: 禁用拨号的原因

func GetSimultaneousConnect 

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

GetSimultaneousConnect 返回上下文中是否设置了同步连接选项。 EXPERIMENTAL 参数:

  • ctx: 要检查的上下文

返回:

  • simconnect: 是否设置了同步连接
  • isClient: 是否为客户端
  • reason: 使用同步连接的原因

func GetUseTransient 

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

GetUseTransient 返回上下文中是否设置了使用临时连接选项。

已弃用: 请改用 GetAllowLimitedConn。 参数:

  • ctx: 要检查的上下文

返回:

  • usetransient: 是否允许临时连接
  • reason: 允许临时连接的原因

func WithAllowLimitedConn 

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

WithAllowLimitedConn 构造一个新的上下文,其中包含一个选项,该选项指示 网络在打开新流时可以使用受限连接。 参数:

  • ctx: 父上下文
  • reason: 允许受限连接的原因

返回:

  • context.Context: 带有允许受限连接选项的新上下文

func WithDialPeerTimeout 

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

WithDialPeerTimeout 返回一个应用了 DialPeer 超时时间的新上下文。

此超时时间会覆盖默认的 DialPeerTimeout,并独立应用于每个拨号。 参数:

  • ctx: 父上下文
  • timeout: 要设置的超时时间

返回:

  • context.Context: 带有拨号超时选项的新上下文

func WithForceDirectDial 

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

EXPERIMENTAL WithForceDirectDial 构造一个新的上下文,其中包含一个选项,该选项指示网络尝试通过拨号强制与对等点建立直接连接,即使已存在到该对等点的代理连接。 参数:

  • ctx: 父上下文
  • reason: 强制直接拨号的原因

返回:

  • context.Context: 带有强制直接拨号选项的新上下文

func WithNoDial 

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

WithNoDial 构造一个新的上下文,其中包含一个选项,该选项指示网络在打开流时不要尝试新的拨号。 参数:

  • ctx: 父上下文
  • reason: 禁用拨号的原因

返回:

  • context.Context: 带有禁用拨号选项的新上下文

func WithSimultaneousConnect 

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

WithSimultaneousConnect 构造一个新的上下文,其中包含一个选项,该选项指示传输在适用的情况下应用打洞逻辑。 EXPERIMENTAL 参数:

  • ctx: 父上下文
  • isClient: 是否为客户端
  • reason: 使用同步连接的原因

返回:

  • context.Context: 带有同步连接选项的新上下文

func WithUseTransient 

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

WithUseTransient 构造一个新的上下文,其中包含一个选项,该选项指示网络 在打开新流时可以使用临时连接。

已弃用: 请改用 WithAllowLimitedConn。 参数:

  • ctx: 父上下文
  • reason: 使用临时连接的原因

返回:

  • context.Context: 带有允许临时连接选项的新上下文

Types

type AddrDelay 

type AddrDelay struct {
	// Addr 是要拨号的地址
	Addr ma.Multiaddr
	// Delay 是拨号前的延迟时间
	Delay time.Duration
}

AddrDelay 提供一个地址以及在该地址应该被拨号之前的延迟

type Conn 

type Conn interface {
	io.Closer

	ConnSecurity
	ConnMultiaddrs
	ConnStat
	ConnScoper

	// ID 返回一个标识符，在当前运行期间唯一标识此主机中的这个 Conn。连接 ID 在重启后可能会重复。
	ID() string

	// NewStream 在此连接上构造一个新的流。
	NewStream(context.Context) (Stream, error)

	// GetStreams 返回此连接上的所有打开的流。
	GetStreams() []Stream

	// IsClosed 返回连接是否完全关闭，以便可以进行垃圾回收。
	IsClosed() bool
}

Conn 是与远程节点的连接，它可以复用流。 通常不需要直接使用 Conn，但它可能对获取对端节点的信息有用: 

stream.Conn().RemotePeer()

type ConnManagementScope 

type ConnManagementScope interface {
	ResourceScopeSpan

	// PeerScope 返回与此连接关联的对等点范围。
	// 如果连接尚未与任何对等点关联,则返回 nil。
	//
	// 返回值:
	//   - PeerScope: 对等点范围
	PeerScope() PeerScope

	// SetPeer 为先前未关联的连接设置对等点
	//
	// 参数:
	//   - peer.ID: 对等点ID
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	SetPeer(peer.ID) error
}

ConnManagementScope 是连接资源范围的低级接口。 此接口由创建和拥有连接范围跨度的系统低级组件使用。

type ConnMultiaddrs 

type ConnMultiaddrs interface {
	// LocalMultiaddr 返回与此连接关联的本地多地址
	LocalMultiaddr() ma.Multiaddr

	// RemoteMultiaddr 返回与此连接关联的远程多地址
	RemoteMultiaddr() ma.Multiaddr
}

ConnMultiaddrs 是一个接口混入，用于提供端点多地址的连接类型。

type ConnScope 

type ConnScope interface {
	ResourceScope
}

ConnScope 是连接范围的用户视图

type ConnScoper 

type ConnScoper interface {
	// Scope 返回此连接的资源作用域的用户视图
	Scope() ConnScope
}

ConnScoper 是一个接口，可以混入到连接接口中以提供资源管理作用域

type ConnSecurity 

type ConnSecurity interface {
	// LocalPeer 返回我们的节点 ID
	LocalPeer() peer.ID

	// RemotePeer 返回远程节点的节点 ID
	RemotePeer() peer.ID

	// RemotePublicKey 返回远程节点的公钥
	RemotePublicKey() ic.PubKey

	// ConnState 返回连接状态的信息
	ConnState() ConnectionState
}

ConnSecurity 是一个接口，可以混入到连接接口中以提供安全方法。

type ConnStat 

type ConnStat interface {
	// Stat 存储与此连接相关的元数据
	Stat() ConnStats
}

ConnStat 是一个接口混入，用于提供连接统计信息的连接类型。

type ConnStats 

type ConnStats struct {
	Stats
	// NumStreams 是连接上的流数量。
	NumStreams int
}

ConnStats 存储与给定Conn相关的元数据。

type Connectedness 

type Connectedness int

Connectedness 表示与给定节点的连接能力。 用于向服务和其他节点发出节点是否可达的信号。 

const (
	// NotConnected 表示没有与节点的连接,也没有额外信息(默认)
	NotConnected Connectedness = iota

	// Connected 表示与节点有开放的、活跃的连接
	Connected

	// Deprecated: CanConnect 已弃用,将在未来版本中移除
	//
	// CanConnect 表示最近与节点连接过,正常终止
	CanConnect

	// Deprecated: CannotConnect 已弃用,将在未来版本中移除
	//
	// CannotConnect 表示最近尝试连接但失败
	// (表示"尝试过但失败了")
	CannotConnect

	// Limited 表示与节点有临时连接,但未完全连接
	Limited
)

func (Connectedness) String 

func (c Connectedness) String() string

String 返回Connectedness的字符串表示。

返回值：

  • string：Connectedness的字符串描述

type ConnectionState 

type ConnectionState struct {
	// 此连接使用的流多路复用器(如果有)。例如: /yamux/1.0.0
	StreamMultiplexer protocol.ID
	// 此连接使用的安全协议(如果有)。例如: /tls/1.0.0
	Security protocol.ID
	// 此连接使用的传输协议。例如: tcp
	Transport string
	// 指示 StreamMultiplexer 是否使用内联多路复用器协商选择
	UsedEarlyMuxerNegotiation bool
}

ConnectionState 保存连接的信息。

type DialRanker 

type DialRanker func([]ma.Multiaddr) []AddrDelay

DialRanker 提供拨号提供的地址的调度

参数：

  • addrs：[]ma.Multiaddr 要调度的地址列表

返回值：

  • []AddrDelay：带延迟的地址列表

type Dialer 

type Dialer interface {
	// Peerstore 返回内部节点存储。这对于告诉拨号器节点的新地址很有用。
	// 或使用在网络上发现的公钥之一。
	//
	// 返回值：
	//   - peerstore.Peerstore：节点存储
	Peerstore() peerstore.Peerstore

	// LocalPeer 返回与此网络关联的本地节点
	//
	// 返回值：
	//   - peer.ID：本地节点ID
	LocalPeer() peer.ID

	// DialPeer 建立与给定节点的连接
	//
	// 参数：
	//   - ctx：context.Context 上下文
	//   - p：peer.ID 目标节点ID
	//
	// 返回值：
	//   - Conn：建立的连接
	//   - error：错误信息
	DialPeer(context.Context, peer.ID) (Conn, error)

	// ClosePeer 关闭与给定节点的连接
	//
	// 参数：
	//   - p：peer.ID 要关闭连接的节点ID
	//
	// 返回值：
	//   - error：错误信息
	ClosePeer(peer.ID) error

	// Connectedness 返回表示连接能力的状态
	//
	// 参数：
	//   - p：peer.ID 要检查连接状态的节点ID
	//
	// 返回值：
	//   - Connectedness：连接状态
	Connectedness(peer.ID) Connectedness

	// Peers 返回已连接的节点
	//
	// 返回值：
	//   - []peer.ID：已连接节点ID列表
	Peers() []peer.ID

	// Conns 返回此Network中的连接
	//
	// 返回值：
	//   - []Conn：连接列表
	Conns() []Conn

	// ConnsToPeer 返回此Network中到给定节点的连接。
	//
	// 参数：
	//   - p：peer.ID 目标节点ID
	//
	// 返回值：
	//   - []Conn：到目标节点的连接列表
	ConnsToPeer(p peer.ID) []Conn

	// Notify/StopNotify 注册和注销信号的通知接收者
	//
	// 参数：
	//   - notifiee：Notifiee 通知接收者
	Notify(Notifiee)
	StopNotify(Notifiee)

	// CanDial 返回拨号器是否可以在addr地址拨号节点p
	//
	// 参数：
	//   - p：peer.ID 目标节点ID
	//   - addr：ma.Multiaddr 目标地址
	//
	// 返回值：
	//   - bool：是否可以拨号
	CanDial(p peer.ID, addr ma.Multiaddr) bool
}

Dialer 表示可以向节点拨号的服务 (这通常就是一个Network,但其他服务可能不需要整个堆栈,因此更容易模拟)

type Direction 

type Direction int

Direction 表示在流中哪个节点发起了连接。 

const (
	// DirUnknown 是默认的方向。
	DirUnknown Direction = iota
	// DirInbound 表示远程节点发起了连接。
	DirInbound
	// DirOutbound 表示本地节点发起了连接。
	DirOutbound
)

func (Direction) String 

func (d Direction) String() string

String 返回Direction的字符串表示。

返回值：

  • string：Direction的字符串描述

type MultiaddrDNSResolver 

type MultiaddrDNSResolver interface {
	// ResolveDNSAddr 解析多地址中的第一个/dnsaddr组件。
	// 递归解析DNSADDRs直到达到递归限制
	//
	// 参数：
	//   - ctx：context.Context 上下文
	//   - expectedPeerID：peer.ID 预期的节点ID
	//   - maddr：ma.Multiaddr 要解析的多地址
	//   - recursionLimit：int 递归限制
	//   - outputLimit：int 输出限制
	//
	// 返回值：
	//   - []ma.Multiaddr：解析后的多地址列表
	//   - error：错误信息
	ResolveDNSAddr(ctx context.Context, expectedPeerID peer.ID, maddr ma.Multiaddr, recursionLimit, outputLimit int) ([]ma.Multiaddr, error)

	// ResolveDNSComponent 解析多地址中的第一个/{dns,dns4,dns6}组件。
	//
	// 参数：
	//   - ctx：context.Context 上下文
	//   - maddr：ma.Multiaddr 要解析的多地址
	//   - outputLimit：int 输出限制
	//
	// 返回值：
	//   - []ma.Multiaddr：解析后的多地址列表
	//   - error：错误信息
	ResolveDNSComponent(ctx context.Context, maddr ma.Multiaddr, outputLimit int) ([]ma.Multiaddr, error)
}

MultiaddrDNSResolver 定义了DNS解析相关的接口。

type Multiplexer 

type Multiplexer interface {
	// NewConn 构造一个新的连接
	NewConn(c net.Conn, isServer bool, scope PeerScope) (MuxedConn, error)
}

Multiplexer 使用流多路复用实现包装 net.Conn，并返回支持在底层 net.Conn 上打开多个流的 MuxedConn

type MuxedConn 

type MuxedConn interface {
	// Close 关闭流多路复用器和底层的 net.Conn。
	io.Closer

	// IsClosed 返回连接是否完全关闭，以便可以进行垃圾回收。
	IsClosed() bool

	// OpenStream 创建一个新流。
	OpenStream(context.Context) (MuxedStream, error)

	// AcceptStream 接受由另一端打开的流。
	AcceptStream() (MuxedStream, error)
}

MuxedConn 表示到远程对等点的连接，该连接已扩展以支持流多路复用。

MuxedConn 允许单个 net.Conn 连接承载多个逻辑独立的双向二进制数据流。

与 network.ConnSecurity 一起，MuxedConn 是 transport.CapableConn 接口的组件， 该接口表示已被"升级"以支持 dep2p 安全通信和流多路复用功能的"原始"网络连接。

type MuxedStream 

type MuxedStream interface {
	io.Reader
	io.Writer

	// Close 关闭流。
	//
	// * 所有用于写入的缓冲数据都将被刷新。
	// * 未来的读取将失败。
	// * 任何正在进行的读/写操作都将被中断。
	//
	// Close 可能是异步的，并且不保证数据的接收。
	//
	// Close 同时关闭流的读取和写入。
	// Close 等同于调用 `CloseRead` 和 `CloseWrite`。重要的是，Close 不会等待任何形式的确认。
	// 如果需要确认，调用者必须调用 `CloseWrite`，然后等待流的响应(或EOF)，
	// 然后调用 Close() 来释放流对象。
	//
	// 当完成流的使用时，用户必须调用 Close() 或 `Reset()` 来丢弃流，即使在调用 `CloseRead` 和/或 `CloseWrite` 之后也是如此。
	io.Closer

	// CloseWrite 关闭流的写入但保持读取打开。
	//
	// CloseWrite 不会释放流，用户仍然必须调用 Close 或 Reset。
	CloseWrite() error

	// CloseRead 关闭流的读取但保持写入打开。
	//
	// 当调用 CloseRead 时，所有正在进行的 Read 调用都会被非 EOF 错误中断，并且后续的 Read 调用都将失败。
	//
	// 调用此函数后对流上新传入数据的处理由具体实现定义。
	//
	// CloseRead 不会释放流，用户仍然必须调用 Close 或 Reset。
	CloseRead() error

	// Reset 关闭流的两端。使用此方法告诉远程端挂断并离开。
	Reset() error

	SetDeadline(time.Time) error
	SetReadDeadline(time.Time) error
	SetWriteDeadline(time.Time) error
}

MuxedStream 是连接中的双向IO管道。

type NATDeviceType 

type NATDeviceType int

NATDeviceType 表示 NAT 设备的类型 

const (
	// NATDeviceTypeUnknown 表示 NAT 设备类型未知
	NATDeviceTypeUnknown NATDeviceType = iota

	// NATDeviceTypeCone 表示 NAT 设备是一个锥形 NAT
	// 锥形 NAT 会将来自相同源 IP 地址和端口的所有出站连接映射到相同的 IP 地址和端口,而不考虑目标地址
	// 根据 RFC 3489,这可能是完全锥形 NAT、受限锥形 NAT 或端口受限锥形 NAT
	// 但是,我们在这里不区分它们,而是简单地将所有此类 NAT 归类为锥形 NAT
	// 只有当远程对等点也在锥形 NAT 后面时,才可以通过打洞实现 NAT 穿透
	// 如果远程对等点在对称 NAT 后面,打洞将失败
	NATDeviceTypeCone

	// NATDeviceTypeSymmetric 表示 NAT 设备是一个对称 NAT
	// 对称 NAT 会将具有不同目标地址的出站连接映射到不同的 IP 地址和端口,即使它们来自相同的源 IP 地址和端口
	// 在 dep2p 中,无论远程对等点的 NAT 类型如何,目前都无法通过打洞实现对称 NAT 的穿透
	NATDeviceTypeSymmetric
)

func (NATDeviceType) String 

func (r NATDeviceType) String() string

String 返回 NATDeviceType 的字符串表示 返回值:

  • string: NAT 设备类型的字符串描述

type NATTransportProtocol 

type NATTransportProtocol int

NATTransportProtocol 表示确定 NAT 设备类型的传输协议 

const (
	// NATTransportUDP 表示已为 UDP 协议确定 NAT 设备类型
	NATTransportUDP NATTransportProtocol = iota
	// NATTransportTCP 表示已为 TCP 协议确定 NAT 设备类型
	NATTransportTCP
)

func (NATTransportProtocol) String 

func (n NATTransportProtocol) String() string

String 返回 NATTransportProtocol 的字符串表示 返回值:

  • string: NAT 传输协议的字符串描述

type Network 

type Network interface {
	Dialer
	io.Closer

	// SetStreamHandler 设置远程端打开新流时的处理程序。此操作是线程安全的。
	//
	// 参数：
	//   - handler：StreamHandler 处理新流的函数
	SetStreamHandler(StreamHandler)

	// NewStream 返回到给定节点p的新流。
	// 如果没有到p的连接,则尝试创建一个。
	//
	// 参数：
	//   - ctx：context.Context 上下文
	//   - p：peer.ID 目标节点ID
	//
	// 返回值：
	//   - Stream：新创建的流
	//   - error：错误信息
	NewStream(context.Context, peer.ID) (Stream, error)

	// Listen 告诉网络开始在给定的多地址上监听。
	//
	// 参数：
	//   - addrs：...ma.Multiaddr 要监听的多地址列表
	//
	// 返回值：
	//   - error：错误信息
	Listen(...ma.Multiaddr) error

	// ListenAddresses 返回此网络监听的地址列表。
	//
	// 返回值：
	//   - []ma.Multiaddr：监听地址列表
	ListenAddresses() []ma.Multiaddr

	// InterfaceListenAddresses 返回此网络监听的地址列表。
	// 它展开"任意接口"地址(/ip4/0.0.0.0, /ip6/::)以使用已知的本地接口。
	//
	// 返回值：
	//   - []ma.Multiaddr：接口监听地址列表
	//   - error：错误信息
	InterfaceListenAddresses() ([]ma.Multiaddr, error)

	// ResourceManager 返回与此网络关联的ResourceManager
	//
	// 返回值：
	//   - ResourceManager：资源管理器
	ResourceManager() ResourceManager
}

Network 是用于连接外部世界的接口。 它用于拨号和监听连接。它使用Swarm来池化连接(参见swarm包和peerstream.Swarm)。 连接使用类TLS协议加密。

type NoopNotifiee 

type NoopNotifiee struct{}

NoopNotifiee 实现了一个不执行任何操作的 Notifiee 接口

func (*NoopNotifiee) Connected 

func (nn *NoopNotifiee) Connected(n Network, c Conn)

Connected 实现了 Notifiee 接口，但不执行任何操作

func (*NoopNotifiee) Disconnected 

func (nn *NoopNotifiee) Disconnected(n Network, c Conn)

Disconnected 实现了 Notifiee 接口，但不执行任何操作

func (*NoopNotifiee) Listen 

func (nn *NoopNotifiee) Listen(n Network, addr ma.Multiaddr)

Listen 实现了 Notifiee 接口，但不执行任何操作

func (*NoopNotifiee) ListenClose 

func (nn *NoopNotifiee) ListenClose(n Network, addr ma.Multiaddr)

ListenClose 实现了 Notifiee 接口，但不执行任何操作

type Notifiee 

type Notifiee interface {
	// Listen 当网络开始监听一个地址时调用
	//
	// 参数：
	//   - n：Network 触发事件的网络实例
	//   - addr：ma.Multiaddr 开始监听的地址
	Listen(Network, ma.Multiaddr)

	// ListenClose 当网络停止监听一个地址时调用
	//
	// 参数：
	//   - n：Network 触发事件的网络实例
	//   - addr：ma.Multiaddr 停止监听的地址
	ListenClose(Network, ma.Multiaddr)

	// Connected 当连接建立时调用
	//
	// 参数：
	//   - n：Network 触发事件的网络实例
	//   - c：Conn 建立的连接
	Connected(Network, Conn)

	// Disconnected 当连接关闭时调用
	//
	// 参数：
	//   - n：Network 触发事件的网络实例
	//   - c：Conn 关闭的连接
	Disconnected(Network, Conn)
}

Notifiee 是一个接口，用于接收来自 Network 的通知。 它定义了一组回调方法，在网络事件发生时被调用。

type NotifyBundle 

type NotifyBundle struct {
	// ListenF 是监听事件的回调函数
	ListenF func(Network, ma.Multiaddr)
	// ListenCloseF 是停止监听事件的回调函数
	ListenCloseF func(Network, ma.Multiaddr)
	// ConnectedF 是连接建立事件的回调函数
	ConnectedF func(Network, Conn)
	// DisconnectedF 是连接关闭事件的回调函数
	DisconnectedF func(Network, Conn)
}

NotifyBundle 通过调用设置在其上的任何函数来实现 Notifiee 接口。 如果函数未设置则不执行任何操作。这是注册通知的简单方式。

func (*NotifyBundle) Connected 

func (nb *NotifyBundle) Connected(n Network, c Conn)

Connected 如果 ConnectedF 不为空则调用它

参数：

  • n：Network 触发事件的网络实例
  • c：Conn 建立的连接

func (*NotifyBundle) Disconnected 

func (nb *NotifyBundle) Disconnected(n Network, c Conn)

Disconnected 如果 DisconnectedF 不为空则调用它

参数：

  • n：Network 触发事件的网络实例
  • c：Conn 关闭的连接

func (*NotifyBundle) Listen 

func (nb *NotifyBundle) Listen(n Network, a ma.Multiaddr)

Listen 如果 ListenF 不为空则调用它

参数：

  • n：Network 触发事件的网络实例
  • a：ma.Multiaddr 监听的地址

func (*NotifyBundle) ListenClose 

func (nb *NotifyBundle) ListenClose(n Network, a ma.Multiaddr)

ListenClose 如果 ListenCloseF 不为空则调用它

参数：

  • n：Network 触发事件的网络实例
  • a：ma.Multiaddr 停止监听的地址

type NullResourceManager 

type NullResourceManager struct{}

NullResourceManager 是用于测试和默认值初始化的存根

func (*NullResourceManager) Close 

func (n *NullResourceManager) Close() error

Close 实现了 ResourceManager 接口的 Close 方法

func (*NullResourceManager) OpenConnection 

func (n *NullResourceManager) OpenConnection(dir Direction, usefd bool, endpoint multiaddr.Multiaddr) (ConnManagementScope, error)

OpenConnection 实现了 ResourceManager 接口的 OpenConnection 方法

func (*NullResourceManager) OpenStream 

func (n *NullResourceManager) OpenStream(p peer.ID, dir Direction) (StreamManagementScope, error)

OpenStream 实现了 ResourceManager 接口的 OpenStream 方法

func (*NullResourceManager) ViewPeer 

func (n *NullResourceManager) ViewPeer(p peer.ID, f func(PeerScope) error) error

ViewPeer 实现了 ResourceManager 接口的 ViewPeer 方法

func (*NullResourceManager) ViewProtocol 

func (n *NullResourceManager) ViewProtocol(p protocol.ID, f func(ProtocolScope) error) error

ViewProtocol 实现了 ResourceManager 接口的 ViewProtocol 方法

func (*NullResourceManager) ViewService 

func (n *NullResourceManager) ViewService(svc string, f func(ServiceScope) error) error

ViewService 实现了 ResourceManager 接口的 ViewService 方法

func (*NullResourceManager) ViewSystem 

func (n *NullResourceManager) ViewSystem(f func(ResourceScope) error) error

ViewSystem 实现了 ResourceManager 接口的 ViewSystem 方法

func (*NullResourceManager) ViewTransient 

func (n *NullResourceManager) ViewTransient(f func(ResourceScope) error) error

ViewTransient 实现了 ResourceManager 接口的 ViewTransient 方法

type NullScope 

type NullScope struct{}

NullScope 是用于测试和默认值初始化的存根

func (*NullScope) BeginSpan 

func (n *NullScope) BeginSpan() (ResourceScopeSpan, error)

BeginSpan 实现了 ResourceScope 接口的 BeginSpan 方法

func (*NullScope) Done 

func (n *NullScope) Done()

Done 实现了 ResourceScopeSpan 接口的 Done 方法

func (*NullScope) Name 

func (n *NullScope) Name() string

Name 实现了 ServiceScope 接口的 Name 方法

func (*NullScope) Peer 

func (n *NullScope) Peer() peer.ID

Peer 实现了 PeerScope 接口的 Peer 方法

func (*NullScope) PeerScope 

func (n *NullScope) PeerScope() PeerScope

PeerScope 实现了 ConnManagementScope 接口的 PeerScope 方法

func (*NullScope) Protocol 

func (n *NullScope) Protocol() protocol.ID

Protocol 实现了 ProtocolScope 接口的 Protocol 方法

func (*NullScope) ProtocolScope 

func (n *NullScope) ProtocolScope() ProtocolScope

ProtocolScope 实现了 StreamManagementScope 接口的 ProtocolScope 方法

func (*NullScope) ReleaseMemory 

func (n *NullScope) ReleaseMemory(size int)

ReleaseMemory 实现了 ResourceScope 接口的 ReleaseMemory 方法

func (*NullScope) ReserveMemory 

func (n *NullScope) ReserveMemory(size int, prio uint8) error

ReserveMemory 实现了 ResourceScope 接口的 ReserveMemory 方法

func (*NullScope) ServiceScope 

func (n *NullScope) ServiceScope() ServiceScope

ServiceScope 实现了 StreamManagementScope 接口的 ServiceScope 方法

func (*NullScope) SetPeer 

func (n *NullScope) SetPeer(peer.ID) error

SetPeer 实现了 ConnManagementScope 接口的 SetPeer 方法

func (*NullScope) SetProtocol 

func (n *NullScope) SetProtocol(proto protocol.ID) error

SetProtocol 实现了 StreamManagementScope 接口的 SetProtocol 方法

func (*NullScope) SetService 

func (n *NullScope) SetService(srv string) error

SetService 实现了 StreamManagementScope 接口的 SetService 方法

func (*NullScope) Stat 

func (n *NullScope) Stat() ScopeStat

Stat 实现了 ResourceScope 接口的 Stat 方法

type PeerScope 

type PeerScope interface {
	ResourceScope

	// Peer 返回此范围的对等点ID
	//
	// 返回值:
	//   - peer.ID: 对等点ID
	Peer() peer.ID
}

PeerScope 是对等点资源范围的接口。

type ProtocolScope 

type ProtocolScope interface {
	ResourceScope

	// Protocol 返回此范围的协议
	//
	// 返回值:
	//   - protocol.ID: 协议ID
	Protocol() protocol.ID
}

ProtocolScope 是协议资源范围的接口。

type Reachability 

type Reachability int

Reachability 表示节点的可达性状态。 

const (
	// ReachabilityUnknown 表示节点的可达性状态未知。
	ReachabilityUnknown Reachability = iota

	// ReachabilityPublic 表示节点可以从公共互联网访问。
	ReachabilityPublic

	// ReachabilityPrivate 表示节点不能从公共互联网访问。
	//
	// 注意:此节点仍可能通过中继可达。
	ReachabilityPrivate
)

func (Reachability) String 

func (r Reachability) String() string

String 返回Reachability的字符串表示。

返回值：

  • string：Reachability的字符串描述

type ResourceManager 

type ResourceManager interface {
	ResourceScopeViewer

	// OpenConnection 创建一个新的连接范围,尚未与任何对等点关联;连接限定在临时范围内。
	// 调用者拥有返回的范围,负责调用 Done 以表示范围的跨度结束。
	//
	// 参数:
	//   - dir: Direction 连接方向
	//   - usefd: bool 是否使用文件描述符
	//   - endpoint: multiaddr.Multiaddr 端点地址
	//
	// 返回值:
	//   - ConnManagementScope: 连接管理范围
	//   - error: 如果发生错误,返回错误信息
	OpenConnection(dir Direction, usefd bool, endpoint multiaddr.Multiaddr) (ConnManagementScope, error)

	// OpenStream 创建一个新的流范围,最初未协商。
	// 未协商的流最初不会附加到任何协议范围,并受临时范围约束。
	// 调用者拥有返回的范围,负责调用 Done 以表示范围的跨度结束。
	//
	// 参数:
	//   - p: peer.ID 对等点ID
	//   - dir: Direction 流方向
	//
	// 返回值:
	//   - StreamManagementScope: 流管理范围
	//   - error: 如果发生错误,返回错误信息
	OpenStream(p peer.ID, dir Direction) (StreamManagementScope, error)

	// Close 关闭资源管理器
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	Close() error
}

ResourceManager 是网络资源管理子系统的接口。 它跟踪和记录资源使用情况,从内部到应用程序,并提供一种机制来根据用户配置的策略限制资源使用。

资源管理基于资源管理范围的概念,其中资源使用受限于一个范围的 DAG, 以下图示说明了资源约束 DAG 的结构: System 

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

ResourceManager 跟踪的基本资源包括内存、流、连接和文件描述符。 这些资源直接影响系统的可用性和性能。

ResourceManager 的工作方式是在资源预留时限制资源使用。当系统组件需要使用资源时, 它会在适当的范围内预留资源。ResourceManager 根据适用的范围限制来控制预留; 如果超出限制,则返回错误(包装 ErrResourceLimitExceeded),由组件相应处理。 在系统的较低层,这通常会导致某种失败,如无法打开流或连接,并传播给程序员。 某些组件可能能够更优雅地处理资源预留失败; 例如,多路复用器尝试为窗口更改增加缓冲区时,将只保留现有窗口大小并继续正常运行, 尽管吞吐量可能会降低。

在某个范围内预留的所有资源在范围关闭时释放。 对于低级范围(主要是连接和流范围),这发生在连接或流关闭时。

服务程序员通常使用资源管理器为其子系统预留内存。 这通过两种方式实现:程序员可以将流附加到服务,流预留的资源自动计入服务预算; 或者程序员可以通过资源管理器接口直接与服务范围交互,使用 ViewService。

应用程序员也可以在某些适用范围内直接预留内存。 为了便于控制流限定的资源记账,系统中定义的所有范围都允许用户创建跨度。 跨度是根植于其他范围的临时范围,当程序员完成时释放其资源。 跨度范围可以形成树,具有嵌套跨度。

典型用法:

  • 系统的低级组件(传输、多路复用器)都可以访问资源管理器,并通过它创建连接和流范围。 这些范围可通过 Conn 和 Stream 对象的 Scope 方法供用户访问,尽管接口更窄。
  • 服务通常围绕流进行,程序员可以将流附加到特定服务。 他们也可以使用 ResourceManager 接口访问服务范围,直接为服务预留内存。
  • 想要记录其网络资源使用的应用程序可以预留内存,通常使用跨度,直接在系统或服务范围内; 他们也可以选择对创建或拥有的流使用适当的流范围。

用户可维护部分:用户可以指定自己的接口实现。 我们在 dep2p-resource-manager 包中提供了一个规范实现。 该包的用户可以为各种范围指定限制,可以是静态的或动态的。

警告:ResourceManager 接口被视为实验性的,在后续版本中可能会更改。

type ResourceScope 

type ResourceScope interface {
	// ReserveMemory 在范围内预留内存/缓冲区空间;单位是字节。
	//
	// 如果 ReserveMemory 返回错误,则没有预留内存,调用者应处理失败情况。
	//
	// priority 参数表示内存预留的优先级。
	// 如果可用内存小于范围限制的(1+prio)/256,预留将失败,
	// 提供了一种机制来优雅地处理可能使系统过载的可选预留。
	// 例如,多路复用器增加窗口缓冲区时将使用低优先级,
	// 只有在系统没有内存压力时才增加缓冲区。
	//
	// 有4个预定义的优先级:Low、Medium、High和Always,
	// 捕获常见模式,但用户可以自由使用适用于其情况的任何粒度。
	//
	// 参数:
	//   - size: int 要预留的内存大小(字节)
	//   - prio: uint8 预留优先级
	//
	// 返回值:
	//   - error: 如果预留失败,返回错误信息
	ReserveMemory(size int, prio uint8) error

	// ReleaseMemory 显式释放之前用 ReserveMemory 预留的内存
	//
	// 参数:
	//   - size: int 要释放的内存大小(字节)
	ReleaseMemory(size int)

	// Stat 检索范围的当前资源使用情况。
	//
	// 返回值:
	//   - ScopeStat: 范围统计信息
	Stat() ScopeStat

	// BeginSpan 创建一个新的跨度范围,根植于此范围
	//
	// 返回值:
	//   - ResourceScopeSpan: 新的跨度范围
	//   - error: 如果发生错误,返回错误信息
	BeginSpan() (ResourceScopeSpan, error)
}

ResourceScope 是所有范围的接口。

type ResourceScopeSpan 

type ResourceScopeSpan interface {
	ResourceScope
	// Done 结束跨度并释放关联的资源。
	Done()
}

ResourceScopeSpan 是一个带有限定跨度的 ResourceScope。 跨度范围是控制流限定的,当程序员调用 Done 时释放所有关联的资源。

示例: 

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

if err := s.ReserveMemory(...); err != nil { ... }
// ... 使用内存

type ResourceScopeViewer 

type ResourceScopeViewer interface {
	// ViewSystem 查看系统范围的资源范围。
	// 系统范围是最高级别的范围,负责所有级别的全局资源使用。
	// 此范围约束所有其他范围并制定全局硬限制。
	//
	// 参数:
	//   - func(ResourceScope) error: 用于查看系统范围的函数
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	ViewSystem(func(ResourceScope) error) error

	// ViewTransient 查看临时(DMZ)资源范围。
	// 临时范围负责正在完全建立过程中的资源。
	// 例如,握手前的新连接不属于任何对等点,但仍需要约束,因为这会打开临时资源使用的攻击途径。
	// 同样,尚未协商协议的流受临时范围约束。
	//
	// 参数:
	//   - func(ResourceScope) error: 用于查看临时范围的函数
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	ViewTransient(func(ResourceScope) error) error

	// ViewService 检索特定服务的范围。
	//
	// 参数:
	//   - string: 服务名称
	//   - func(ServiceScope) error: 用于查看服务范围的函数
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	ViewService(string, func(ServiceScope) error) error

	// ViewProtocol 查看特定协议的资源管理范围。
	//
	// 参数:
	//   - protocol.ID: 协议ID
	//   - func(ProtocolScope) error: 用于查看协议范围的函数
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	ViewProtocol(protocol.ID, func(ProtocolScope) error) error

	// ViewPeer 查看特定对等点的资源管理范围。
	//
	// 参数:
	//   - peer.ID: 对等点ID
	//   - func(PeerScope) error: 用于查看对等点范围的函数
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	ViewPeer(peer.ID, func(PeerScope) error) error
}

ResourceScopeViewer 是一个混合接口,提供访问顶级范围的视图方法。

type ScopeStat 

type ScopeStat struct {
	// NumStreamsInbound 是入站流的数量
	NumStreamsInbound int
	// NumStreamsOutbound 是出站流的数量
	NumStreamsOutbound int
	// NumConnsInbound 是入站连接的数量
	NumConnsInbound int
	// NumConnsOutbound 是出站连接的数量
	NumConnsOutbound int
	// NumFD 是文件描述符的数量
	NumFD int
	// Memory 是内存使用量(字节)
	Memory int64
}

ScopeStat 是包含资源记账信息的结构。

type ServiceScope 

type ServiceScope interface {
	ResourceScope

	// Name 返回此服务的名称
	//
	// 返回值:
	//   - string: 服务名称
	Name() string
}

ServiceScope 是服务资源范围的接口

type Stats 

type Stats struct {
	// Direction 指定这是入站还是出站连接。
	Direction Direction
	// Opened 是此连接打开的时间戳。
	Opened time.Time
	// Limited 表示此连接是受限的。
	// 可能受字节或时间限制。实际上,这是通过circuit v2中继形成的连接。
	Limited bool
	// Extra 存储关于此连接的额外元数据。
	Extra map[interface{}]interface{}
}

Stats 存储与给定Stream/Conn相关的元数据。

type Stream 

type Stream interface {
	MuxedStream

	// ID 返回一个标识符,在本次运行期间唯一标识此主机中的此 Stream。
	// Stream ID 可能在重启后重复。
	ID() string

	// Protocol 返回流的协议 ID
	Protocol() protocol.ID
	// SetProtocol 设置流的协议 ID
	SetProtocol(id protocol.ID) error

	// Stat 返回与此流相关的元数据。
	Stat() Stats

	// Conn 返回此流所属的连接。
	Conn() Conn

	// Scope 返回此流的资源范围的用户视图
	Scope() StreamScope
}

Stream 表示 dep2p 网络中两个代理之间的双向通道。 "代理"可以根据需要进行细分,可以是"请求->响应"对,也可以是完整的协议。

Stream 在底层由多路复用器支持。

type StreamHandler 

type StreamHandler func(Stream)

StreamHandler 是用于监听远程端打开的流的函数类型。

type StreamManagementScope 

type StreamManagementScope interface {
	ResourceScopeSpan

	// ProtocolScope 返回与此流关联的协议资源范围。
	// 如果流未与任何协议范围关联,则返回 nil。
	//
	// 返回值:
	//   - ProtocolScope: 协议范围
	ProtocolScope() ProtocolScope

	// SetProtocol 为先前未协商的流设置协议
	//
	// 参数:
	//   - proto: protocol.ID 协议ID
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	SetProtocol(proto protocol.ID) error

	// ServiceScope 返回拥有流的服务(如果有)。
	//
	// 返回值:
	//   - ServiceScope: 服务范围
	ServiceScope() ServiceScope

	// SetService 设置拥有此流的服务。
	//
	// 参数:
	//   - srv: string 服务名称
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	SetService(srv string) error

	// PeerScope 返回与此流关联的对等点资源范围。
	//
	// 返回值:
	//   - PeerScope: 对等点范围
	PeerScope() PeerScope
}

StreamManagementScope 是流资源范围的接口。 此接口由创建和拥有流范围跨度的系统低级组件使用。

type StreamScope 

type StreamScope interface {
	ResourceScope

	// SetService 设置拥有此流的服务。
	//
	// 参数:
	//   - srv: string 服务名称
	//
	// 返回值:
	//   - error: 如果发生错误,返回错误信息
	SetService(srv string) error
}

StreamScope 是 StreamScope 的用户视图。

Source Files

View all Source files

Directories

Path Synopsis
Package mocknetwork 是一个由 GoMock 生成的包
 Package mocknetwork 是一个由 GoMock 生成的包

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.