Documentation
¶
Overview ¶
Package webrtc provides a WebRTC-based peer-to-peer transport layer built on pion/webrtc v4. It offers a net.Conn-like abstraction that uses DataChannel as the transport substrate, with in-memory signaling channels for SDP Offer/Answer exchange.
Basic usage:
signal := webrtc.NewSignal()
// Listener side (goroutine)
listener, err := webrtc.Listen(signal)
buf := make([]byte, 1024)
n, _ := listener.Read(buf)
// Dialer side
conn, err := webrtc.Dial(signal)
conn.Write([]byte("hello"))
Index ¶
- Variables
- func ConnAsXfer(c *Conn) xfer.Conn
- func ResetSignalingTimeout()
- func SetHostOnly(hostOnly bool)
- func SetLogger(l *slog.Logger)
- func SetLoggerDefault()
- func SetRejectPrivateRemoteCandidates(reject bool)
- func SetSTUNServers(servers []string)
- func SetSignalingTimeout(d time.Duration)
- func SetTURNCredential(username, password string)
- func SetTURNRESTURL(urlStr, username, service string) error
- func SetTURNServers(urls []string)
- func SetVerbose(v bool)
- type Conn
- func Dial(signal *Signal) (*Conn, error)
- func DialWithSignaler(peer string, sig Signaler) (*Conn, error)
- func DialWithSignalerCtx(ctx context.Context, peer string, sig Signaler) (*Conn, error)
- func DialWithSignalerOptsCtx(ctx context.Context, peer string, sig Signaler, opts *ICEOptions) (*Conn, error)
- func Listen(signal *Signal) (*Conn, error)
- func ListenWithSignaler(peer string, sig Signaler) (*Conn, error)
- func ListenWithSignalerCtx(ctx context.Context, peer string, sig Signaler) (*Conn, error)
- func ListenWithSignalerOptsCtx(ctx context.Context, peer string, sig Signaler, opts *ICEOptions) (*Conn, error)
- func (c *Conn) Close() error
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) Read(b []byte) (int, error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) RemotePeerID() string
- func (c *Conn) SetDeadline(_ time.Time) error
- func (c *Conn) SetReadDeadline(_ time.Time) error
- func (c *Conn) SetWriteDeadline(_ time.Time) error
- func (c *Conn) Write(b []byte) (int, error)
- type ICEOptions
- type Signal
- type Signaler
Constants ¶
This section is empty.
Variables ¶
var ErrNoIncomingConnection = errors.New("webrtc: 无对端在超时窗口内发起连接")
ListenWithSignaler 通过指定的 Signaler 等待连接(跨机器可用)。 等待发给本节点的 Offer,Answer 回给 offer 的发送方。 整体等待受 signalingTimeout 约束,避免无拨号方时永久挂起。 该便捷包装使用 context.Background();需要外部 ctx 取消请用 ListenWithSignalerCtx。 ErrNoIncomingConnection 表示信令/数据通道等待超时(signalingTimeout 或 defaultICETimeout 内无对端发起连接)。 监听方可将此视为"空闲"而非"失败:不应触发重注册/退避重连,只需继续监听(P1-11)。
Functions ¶
func ConnAsXfer ¶ added in v0.11.1
ConnAsXfer 把一个已建立的 WebRTC *Conn 包装成 xfer.Conn, 供上层 mux 复用(网络信令建立后,把 DataChannel 当作 xfer 消息通道)。
func ResetSignalingTimeout ¶ added in v0.11.1
func ResetSignalingTimeout()
ResetSignalingTimeout 恢复信令等待整体超时为默认值(30s)。 --manual 场景 SetSignalingTimeout 调大后,命令/测试结束应恢复默认, 避免全局泄漏污染库内嵌场景与后续测试(S69)。
func SetHostOnly ¶ added in v0.11.1
func SetHostOnly(hostOnly bool)
SetHostOnly 控制是否使用仅本机 host 候选(不加 STUN)。 主要用于测试与无 STUN 可达性的内网场景;生产跨公网打洞请保持默认(含 STUN)。 注意:host-only 模式下远程 ICE 候选过滤全部放行(本机 loopback 候选合法), 该开关同时作为安全过滤(SetRemoteIPFilter)的测试专用旁路。
func SetLoggerDefault ¶ added in v0.15.0
func SetLoggerDefault()
SetLoggerDefault 恢复 slog.Default 兜底。
func SetRejectPrivateRemoteCandidates ¶ added in v0.11.1
func SetRejectPrivateRemoteCandidates(reject bool)
SetRejectPrivateRemoteCandidates 收紧/放开私网远程候选过滤。 默认保持私网放行以支持 LAN mesh;安全敏感部署可显式开启。 在创建任何连接前调用(命令入口处)。
func SetSTUNServers ¶ added in v0.11.1
func SetSTUNServers(servers []string)
SetSTUNServers 覆盖 STUN 服务器列表(调用方传入 --stun 的多个值)。 空列表 = 不添加任何 STUN(等价 host-only 候选收集);传 nil 恢复默认。 在创建任何连接前调用(命令入口处)。非法 URL(scheme/host:port 不合法)打 Warn 并跳过。
func SetSignalingTimeout ¶ added in v0.11.1
SetSignalingTimeout 覆盖信令等待整体超时(--manual 人工拷文件可调大)。
func SetTURNCredential ¶ added in v0.11.1
func SetTURNCredential(username, password string)
SetTURNCredential 设置 TURN 服务器凭据(静态用户名/密码,pion password 模式)。
func SetTURNRESTURL ¶ added in v0.11.1
SetTURNRESTURL 设置 TURN REST API 短期凭证端点(coturn 标准,与静态凭据并存,REST 优先)。 url 形如 https://turn.example.com/turn;username 是 REST API 的认证用户名; service 可选(透传给服务端,如用于区分 realm/service)。
安全边界(fail-closed):URL 默认强推 https;明文 http 仅限 loopback(本机调试), 非 loopback 的 http 拒绝(否则凭据与 TURN 流量可被中间人读取,对齐 sync_remotes 明文校验模式)。url 传空串清空 REST 配置与缓存(供测试复位/CLI 停用)。 校验失败返回 error 且不修改当前配置(保持之前的值)。
func SetTURNServers ¶ added in v0.11.1
func SetTURNServers(urls []string)
SetTURNServers 覆盖 TURN 服务器列表(调用方传入 --turn 的多个值)。 nil = 清空(不使用 TURN);否则过滤掉空串与非法 URL(打 Warn 并跳过), 存储时用独立切片,避免与调用方 slice 共享底层数组(防后续修改污染)。 注:只设服务器不设凭据时 defaultConfig 不下发 TURN 条目(pion 需要 Username/Credential,否则 newPC 校验失败)。
func SetVerbose ¶ added in v0.11.1
func SetVerbose(v bool)
SetVerbose 开启 pion 底层打洞日志(candidate/STUN/DTLS 明细),供 --verbose 排障使用。 在创建任何连接前调用(命令入口处);生效于后续创建的 PeerConnection。
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn implements net.Conn over a WebRTC DataChannel.
func DialWithSignaler ¶ added in v0.11.1
DialWithSignaler 通过指定的 Signaler 建立连接(跨机器可用)。 peer 是远端节点标识:Offer 发给 peer,Answer 等待来自 peer。 整体等待受 signalingTimeout 约束,避免对端离线时永久挂起。 该便捷包装使用 context.Background();需要外部 ctx 取消请用 DialWithSignalerCtx。
func DialWithSignalerCtx ¶ added in v0.11.1
DialWithSignalerCtx 通过指定的 Signaler 建立连接(跨机器可用)。 peer 是远端节点标识:Offer 发给 peer,Answer 等待来自 peer。 整体等待受 ctx 与 signalingTimeout 共同约束:ctx 取消立即返回 ctx.Err(), 对端离线超时返回带候选诊断的错误。
func DialWithSignalerOptsCtx ¶ added in v0.11.1
func DialWithSignalerOptsCtx(ctx context.Context, peer string, sig Signaler, opts *ICEOptions) (*Conn, error)
DialWithSignalerOptsCtx 是 DialWithSignalerCtx 的**实例级 ICE 配置**版本(Y 二期): opts==nil 完全沿用包级全局;非 nil 时完全自决(见 ICEOOptions 契约)。 同进程内多任务/多租户各带自己的 STUN/TURN 时用本函数,互不干扰。
func ListenWithSignaler ¶ added in v0.11.1
func ListenWithSignalerCtx ¶ added in v0.11.1
ListenWithSignalerCtx 通过指定的 Signaler 等待连接(跨机器可用)。 等待发给本节点的 Offer,Answer 回给 offer 的发送方。 整体等待受 ctx 与 signalingTimeout 共同约束:ctx 取消立即返回 ctx.Err()。
func ListenWithSignalerOptsCtx ¶ added in v0.11.1
func ListenWithSignalerOptsCtx(ctx context.Context, peer string, sig Signaler, opts *ICEOptions) (*Conn, error)
ListenWithSignalerOptsCtx 是 ListenWithSignalerCtx 的**实例级 ICE 配置**版本(Y 二期): 语义同 DialWithSignalerOptsCtx(opts==nil 回落到全局;非 nil 完全自决)。
func (*Conn) Read ¶
Read 读取一条消息。与底层读并行监听 closeCh:Close 后 Read 可被确定性唤醒并 立即返回错误(pion detached DataChannel 在 pc.Close 后不保证唤醒读循环, 实测可能阻塞数秒甚至更久)。Read-after-Close 返回 xfer.ErrConnClosed。
func (*Conn) RemoteAddr ¶
func (*Conn) RemotePeerID ¶ added in v0.11.1
RemotePeerID 返回对端信令身份(拨号方=目标 peer;监听方=offer 发送方)。 供 mesh accept 侧判断拨号者是否 discovery peer(disc- 前缀)并注册链路。
type ICEOptions ¶ added in v0.11.1
type ICEOptions struct {
// STUNServers 是 STUN 列表(opts 非 nil 时生效;空 = 不用 STUN)。
STUNServers []string
// TURNServers 是 TURN 列表(需与 TURNUser/TURNPassword 同时提供才下发)。
TURNServers []string
// TURNUser / TURNPassword 是 TURN 静态凭据。
TURNUser string
TURNPassword string
}
ICEOptions 是**实例级** ICE 配置(Y 二期:server 侧拨号/监听需要与 CLI 全局配置解耦—— 若只有包级 Set*,一个进程内的多任务/多租户只能共享一份,将来必然返工)。
语义(契约,勿放宽):
- `opts == nil` → **完全**沿用包级全局(CLI 现行为零变更,含 TURN REST 短期凭据机制);
- `opts != nil` → **完全自决**:只用本结构声明的 STUN/TURN/静态凭据;**不读包级全局**、 **不使用 TURN REST 机制**(避免「实例配置被全局机制悄悄覆盖」这类难查行为);
- 两者都**不修改**包级全局(实例配置不得污染其他调用方)。
type Signal ¶
Signal provides in-memory channels for SDP Offer/Answer exchange. 注意:chan buffer 为 1,仅支持单连接 rendezvous(单拨号-单监听); 生产 mesh/p2p 请使用 hub.HubSignaler 或 manualSignaler(不经本类型)。
type Signaler ¶ added in v0.11.1
type Signaler interface {
// SendOffer 向对端 to 发送 Offer SDP。
SendOffer(to, sdp string) error
// WaitOffer 阻塞等待对端发来的 Offer SDP,返回发送方节点 ID。
WaitOffer(ctx context.Context) (from, sdp string, err error)
// SendAnswer 向对端 to 发送 Answer SDP。
SendAnswer(to, sdp string) error
// WaitAnswer 阻塞等待对端发来的 Answer SDP,返回发送方节点 ID。
WaitAnswer(ctx context.Context) (from, sdp string, err error)
}
Signaler 抽象 SDP Offer/Answer(以及可选 ICE candidate)的交换通道。
方向语义(重要):
- SendOffer/SendAnswer 的 to 是目标对端节点 ID;
- WaitOffer/WaitAnswer 等待「发给本节点」的消息,返回 from(发送方节点 ID)。
进程内实现用 Signal channel;跨机器实现可走 hub 的 HTTP 存转信令桥。