dep2phttp

Documentation

Overview

HTTP semantics with dep2p. Can use a dep2p stream transport or stock HTTP transports. This API is experimental and will likely change soon. Implements [dep2p spec #508](https://github.com/dep2p/specs/pull/508).

Index

• Constants
• Variables
• func PreferHTTPTransport(o roundTripperOpts) roundTripperOpts
• func ServerMustAuthenticatePeerID(o roundTripperOpts) roundTripperOpts
• type Host
  • func (h *Host) AddPeerMetadata(server peer.ID, meta PeerMeta)
  • func (h *Host) Addrs() []ma.Multiaddr
  • func (h *Host) Close() error
  • func (h *Host) GetPeerMetadata(server peer.ID) (PeerMeta, bool)
  • func (h *Host) NamespaceRoundTripper(roundtripper http.RoundTripper, p protocol.ID, server peer.ID) (*namespacedRoundTripper, error)
  • func (h *Host) NamespacedClient(p protocol.ID, server peer.AddrInfo, opts ...RoundTripperOption) (http.Client, error)
  • func (h *Host) NewConstrainedRoundTripper(server peer.AddrInfo, opts ...RoundTripperOption) (http.RoundTripper, error)
  • func (h *Host) PeerID() peer.ID
  • func (h *Host) RemovePeerMetadata(server peer.ID)
  • func (h *Host) RoundTrip(r *http.Request) (*http.Response, error)
  • func (h *Host) Serve() error
  • func (h *Host) SetHTTPHandler(p protocol.ID, handler http.Handler)
  • func (h *Host) SetHTTPHandlerAtPath(p protocol.ID, path string, handler http.Handler)
  • func (h *Host) SetPeerMetadata(server peer.ID, meta PeerMeta)
• type PeerMeta
• type PeerMetadataGetter
• type ProtocolMeta
• type RoundTripperOption
• type WellKnownHandler
  • func (h *WellKnownHandler) AddProtocolMeta(p protocol.ID, protocolMeta ProtocolMeta)
  • func (h *WellKnownHandler) RemoveProtocolMeta(p protocol.ID)
  • func (h *WellKnownHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const LegacyWellKnownProtocols = "/.well-known/dep2p"

LegacyWellKnownProtocols 指向早期 dep2p+http 规范草案中使用的 well-known 资源。 一些用户已经部署了这个版本,需要向后兼容。 希望将来可以逐步淘汰。上下文: https://github.com/dep2p/pull/2797

const ProtocolIDForMultistreamSelect = "/http/1.1"

用于多流选择的协议ID

const WellKnownProtocols = "/.well-known/dep2p/protocols"

well-known 协议路径

Variables

var ErrNoListeners = errors.New("没有可监听的地址")

ErrNoListeners 表示没有可用的监听器

var WellKnownRequestTimeout = 30 * time.Second

默认的 well-known 请求超时时间

Functions

func PreferHTTPTransport

func PreferHTTPTransport(o roundTripperOpts) roundTripperOpts

PreferHTTPTransport 告诉 RoundTripper 构造器优先使用 HTTP 传输 (而不是 dep2p 流传输)。这在需要利用 HTTP 缓存等场景下很有用。 参数:

• o: roundTripperOpts - RoundTripper 选项

返回:

• roundTripperOpts: 更新后的 RoundTripper 选项

func ServerMustAuthenticatePeerID

func ServerMustAuthenticatePeerID(o roundTripperOpts) roundTripperOpts

ServerMustAuthenticatePeerID 告诉 RoundTripper 构造器必须验证服务器的对等节点 ID。 注意:目前这意味着我们不能使用原生 HTTP 传输(HTTP 对等节点 ID 验证尚未实现: https://github.com/dep2p/specs/pull/564)。 参数:

• o: roundTripperOpts - RoundTripper 选项

返回:

• roundTripperOpts: 更新后的 RoundTripper 选项

Types

type Host

type Host struct {
	// StreamHost 是用于在 dep2p 流上进行 HTTP 通信的基于流的 dep2p 主机,可以为 nil
	StreamHost host.Host
	// ListenAddrs 是要监听的请求地址。多地址必须是有效的 HTTP(s) 多地址。
	// 仅支持 HTTP 传输的多地址(必须以 /http 或 /https 结尾)。
	ListenAddrs []ma.Multiaddr
	// TLSConfig 是服务器使用的 TLS 配置
	TLSConfig *tls.Config
	// InsecureAllowHTTP 表示是否允许服务器通过 TCP 提供未加密的 HTTP 请求
	InsecureAllowHTTP bool
	// ServeMux 是服务器用于处理请求的 http.ServeMux。如果为 nil,将创建一个新的 serve mux。
	// 用户可以手动向此 mux 添加处理程序,而不是使用 `SetHTTPHandler`,但如果这样做,他们也应该更新 WellKnownHandler 的协议映射。
	ServeMux *http.ServeMux

	// DefaultClientRoundTripper 是客户端在通过 HTTP 传输发出请求时使用的默认 http.RoundTripper。
	// 这必须是 `*http.Transport` 类型,以便可以克隆传输并配置 `TLSClientConfig` 字段。
	// 如果未设置,将在首次使用时创建一个新的 `http.Transport`。
	DefaultClientRoundTripper *http.Transport

	// WellKnownHandler 是 well-known 资源的 http 处理程序。
	// 它负责与其他节点共享此节点的协议元数据。
	// 用户只有在使用预先存在路由设置自己的 ServeMux 时才需要关心这个。
	// 默认情况下,当用户调用 `SetHTTPHandler` 或 `SetHTTPHandlerAtPath` 时,新协议会被添加到这里。
	WellKnownHandler WellKnownHandler

	// EnableCompatibilityWithLegacyWellKnownEndpoint 允许与旧版本的规范兼容,该规范将 well-known 资源定义为: .well-known/dep2p。
	// 对于服务器,这意味着在旧路径和当前路径上都托管 well-known 资源。
	// 对于客户端,这意味着并行发出两个请求并选择第一个成功的请求。
	//
	// 长期来看,一旦足够多的用户升级到较新的 go-dep2p 版本,我们就可以删除所有这些代码,这应该被弃用。
	EnableCompatibilityWithLegacyWellKnownEndpoint bool
	// contains filtered or unexported fields
}

Host 是一个用于 HTTP 语义的请求/响应的 dep2p 主机。 这与面向流的主机(如核心 host.Host 接口)不同。 其零值(&Host{})可用。不要按值复制。 参见示例了解用法。

警告:这是实验性的。API 可能会发生变化。

func (*Host) AddPeerMetadata

func (h *Host) AddPeerMetadata(server peer.ID, meta PeerMeta)

AddPeerMetadata 合并给定对等节点的协议元数据到 HTTP 主机 当您有对等节点协议映射的带外知识时很有用 参数:

• server: peer.ID - 服务器 ID
• meta: PeerMeta - 元数据

func (*Host) Addrs

func (h *Host) Addrs() []ma.Multiaddr

Addrs 返回所有监听地址 返回:

• []ma.Multiaddr: 监听地址列表

func (*Host) Close

func (h *Host) Close() error

Close 关闭 HTTP 主机 参数：无 返回值：error - 如果发生错误则返回错误信息

func (*Host) GetPeerMetadata

func (h *Host) GetPeerMetadata(server peer.ID) (PeerMeta, bool)

GetPeerMetadata 从 HTTP 主机获取对等节点的缓存协议元数据 参数:

• server: peer.ID - 服务器 ID

返回:

• PeerMeta: 对等节点元数据
• bool: 是否找到元数据

func (*Host) NamespaceRoundTripper

func (h *Host) NamespaceRoundTripper(roundtripper http.RoundTripper, p protocol.ID, server peer.ID) (*namespacedRoundTripper, error)

NamespaceRoundTripper 返回一个限定在指定服务器上指定协议的 http.RoundTripper 参数:

• roundtripper: HTTP 请求处理器
• p: 协议 ID
• server: 对等节点 ID

返回:

• *namespacedRoundTripper: 命名空间限定的 RoundTripper
• error: 错误信息

func (*Host) NamespacedClient

func (h *Host) NamespacedClient(p protocol.ID, server peer.AddrInfo, opts ...RoundTripperOption) (http.Client, error)

NamespacedClient 返回一个限定在指定服务器上指定协议的 http.Client 每次调用都会创建一个新的 RoundTripper 如果需要创建多个命名空间客户端,建议直接创建 RoundTripper 并自行命名空间限定,然后基于命名空间 RoundTripper 创建客户端 参数:

• p: 协议 ID
• server: 对等节点地址信息
• opts: RoundTripper 选项

返回:

• http.Client: HTTP 客户端
• error: 错误信息

func (*Host) NewConstrainedRoundTripper

func (h *Host) NewConstrainedRoundTripper(server peer.AddrInfo, opts ...RoundTripperOption) (http.RoundTripper, error)

NewConstrainedRoundTripper 返回一个可以向指定服务器发送 HTTP 请求的 http.RoundTripper 它可以使用 HTTP 传输或基于流的传输。允许传入空的 server.ID 如果服务器有多个地址,它将使用以下规则选择最佳传输(流与标准 HTTP):

• 如果设置了 PreferHTTPTransport,使用 HTTP 传输
• 如果设置了 ServerMustAuthenticatePeerID,使用流传输,因为 HTTP 传输尚不支持对等节点 ID 认证
• 如果已经在流传输上有连接,使用该连接
• 否则,如果两种传输都可用,使用 HTTP 传输

参数:

• server: 对等节点地址信息
• opts: RoundTripper 选项

返回:

• http.RoundTripper: HTTP 传输
• error: 错误信息

func (*Host) PeerID

func (h *Host) PeerID() peer.ID

PeerID 返回底层流主机的对等节点 ID，如果没有流主机则返回零值 返回:

• peer.ID: 对等节点 ID

func (*Host) RemovePeerMetadata

func (h *Host) RemovePeerMetadata(server peer.ID)

RemovePeerMetadata 从 HTTP 主机移除对等节点的协议元数据 参数:

• server: peer.ID - 服务器 ID

func (*Host) RoundTrip

func (h *Host) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip 实现 http.RoundTripper 接口 允许将 Host 用作 http.Client 的传输层 参数:

• r: *http.Request - HTTP 请求对象

返回:

• *http.Response: HTTP 响应对象
• error: 错误信息

处理流程: 1. 根据 URL scheme 选择不同的处理方式:

• http/https: 使用默认传输
• multiaddr: 继续处理 multiaddr 方案
• 其他: 返回不支持的协议错误

2. 对于 multiaddr:

• 解析 multiaddr URL 并标准化
• 如果是 HTTP 请求:
• 构建标准 URL
• 使用默认或自定义传输处理请求
• 如果是基于流的请求:
• 验证 StreamHost 和对等节点 ID
• 将地址添加到对等节点存储
• 创建流传输并处理请求

func (*Host) Serve

func (h *Host) Serve() error

Serve 启动 HTTP 传输监听器。总是返回一个非空错误。 如果没有监听器，返回 ErrNoListeners。 参数：无 返回值：error - 如果发生错误则返回错误信息

func (*Host) SetHTTPHandler

func (h *Host) SetHTTPHandler(p protocol.ID, handler http.Handler)

SetHTTPHandler 为给定协议设置 HTTP 处理器。自动管理已知资源映射。 对处理器调用 http.StripPrefix，因此处理器不会感知其前缀路径。 参数：

• p: protocol.ID - 协议标识符
• handler: http.Handler - HTTP 处理器

func (*Host) SetHTTPHandlerAtPath

func (h *Host) SetHTTPHandlerAtPath(p protocol.ID, path string, handler http.Handler)

SetHTTPHandlerAtPath 使用给定路径为指定协议设置 HTTP 处理器。自动管理已知资源映射。 对处理器调用 http.StripPrefix，因此处理器不会感知其前缀路径。 参数：

• p: protocol.ID - 协议标识符
• path: string - 处理器路径
• handler: http.Handler - HTTP 处理器

func (*Host) SetPeerMetadata

func (h *Host) SetPeerMetadata(server peer.ID, meta PeerMeta)

SetPeerMetadata 将对等节点的协议元数据添加到 HTTP 主机 当您有对等节点协议映射的带外知识时很有用 参数:

• server: peer.ID - 服务器 ID
• meta: PeerMeta - 元数据

type PeerMeta

type PeerMeta map[protocol.ID]ProtocolMeta

PeerMeta 是协议ID到协议元数据的映射

type PeerMetadataGetter

type PeerMetadataGetter interface {
	// GetPeerMetadata 获取对等节点的元数据
	// 返回:
	//   - PeerMeta: 对等节点的元数据
	//   - error: 错误信息
	GetPeerMetadata() (PeerMeta, error)
}

PeerMetadataGetter 允许 RoundTripper 实现特定的方式来缓存对等节点的协议映射

type ProtocolMeta

type ProtocolMeta struct {
	// Path 定义了此协议使用的 HTTP 路径前缀
	Path string `json:"path"`
}

ProtocolMeta 是协议的元数据

type RoundTripperOption

type RoundTripperOption func(o roundTripperOpts) roundTripperOpts

RoundTripperOption 是一个函数类型,用于配置 RoundTripper 选项 参数:

• o: roundTripperOpts - RoundTripper 选项

返回:

• roundTripperOpts: 更新后的 RoundTripper 选项

type WellKnownHandler

type WellKnownHandler struct {
	// contains filtered or unexported fields
}

WellKnownHandler 是一个处理 well-known 资源的 http.Handler

func (*WellKnownHandler) AddProtocolMeta

func (h *WellKnownHandler) AddProtocolMeta(p protocol.ID, protocolMeta ProtocolMeta)

AddProtocolMeta 添加协议元数据 参数:

• p: 协议ID
• protocolMeta: 协议元数据

func (*WellKnownHandler) RemoveProtocolMeta

func (h *WellKnownHandler) RemoveProtocolMeta(p protocol.ID)

RemoveProtocolMeta 移除协议元数据 参数:

• p: 要移除的协议ID

func (*WellKnownHandler) ServeHTTP

func (h *WellKnownHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP 实现 http.Handler 接口,处理 well-known 请求 参数:

• w: HTTP 响应写入器
• r: HTTP 请求