webrtc

package module
v0.25.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func ConnAsXfer(c *Conn) xfer.Conn

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 SetLogger added in v0.15.0

func SetLogger(l *slog.Logger)

SetLogger 注入包级日志器(nil 恢复 slog.Default 兜底)。

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

func SetSignalingTimeout(d time.Duration)

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

func SetTURNRESTURL(urlStr, username, service string) error

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 Dial

func Dial(signal *Signal) (*Conn, error)

Dial initiates a connection. Listen must be started first.

func DialWithSignaler added in v0.11.1

func DialWithSignaler(peer string, sig Signaler) (*Conn, error)

DialWithSignaler 通过指定的 Signaler 建立连接(跨机器可用)。 peer 是远端节点标识:Offer 发给 peer,Answer 等待来自 peer。 整体等待受 signalingTimeout 约束,避免对端离线时永久挂起。 该便捷包装使用 context.Background();需要外部 ctx 取消请用 DialWithSignalerCtx。

func DialWithSignalerCtx added in v0.11.1

func DialWithSignalerCtx(ctx context.Context, peer string, sig Signaler) (*Conn, error)

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 Listen

func Listen(signal *Signal) (*Conn, error)

Listen waits for an incoming connection. Must be started before Dial.

func ListenWithSignaler added in v0.11.1

func ListenWithSignaler(peer string, sig Signaler) (*Conn, error)

func ListenWithSignalerCtx added in v0.11.1

func ListenWithSignalerCtx(ctx context.Context, peer string, sig Signaler) (*Conn, error)

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) Close

func (c *Conn) Close() error

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read 读取一条消息。与底层读并行监听 closeCh:Close 后 Read 可被确定性唤醒并 立即返回错误(pion detached DataChannel 在 pc.Close 后不保证唤醒读循环, 实测可能阻塞数秒甚至更久)。Read-after-Close 返回 xfer.ErrConnClosed。

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) RemotePeerID added in v0.11.1

func (c *Conn) RemotePeerID() string

RemotePeerID 返回对端信令身份(拨号方=目标 peer;监听方=offer 发送方)。 供 mesh accept 侧判断拨号者是否 discovery peer(disc- 前缀)并注册链路。

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(_ time.Time) error

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(_ time.Time) error

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(_ time.Time) error

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

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

type Signal struct {
	Offer  chan string
	Answer chan string
}

Signal provides in-memory channels for SDP Offer/Answer exchange. 注意:chan buffer 为 1,仅支持单连接 rendezvous(单拨号-单监听); 生产 mesh/p2p 请使用 hub.HubSignaler 或 manualSignaler(不经本类型)。

func NewSignal

func NewSignal() *Signal

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 存转信令桥。

Directories

Path Synopsis
internal
icecfg
Package icecfg 控制 webrtc 传输的 ICE UDP 候选收集行为,供 webrtc 主包读取、 供 webrtctest 测试工具包设置。
Package icecfg 控制 webrtc 传输的 ICE UDP 候选收集行为,供 webrtc 主包读取、 供 webrtctest 测试工具包设置。
Package webrtctest 提供 webrtc 传输的测试辅助工具。
Package webrtctest 提供 webrtc 传输的测试辅助工具。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址