protocol

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 20, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ChunkSize is the DATA payload size for a full chunk; the final chunk
	// may be smaller. 256 KB sits well under pion's ~1 GB SCTP max message
	// size.
	ChunkSize = 256 * 1024

	// PrimaryLabel is the DataChannel label used for the single channel.
	PrimaryLabel = "primary"
	// ControlLabel is the DataChannel label on the control PeerConnection
	// in multi-PC mode. Data PCs use LabelForDataPeer(i).
	ControlLabel = "control"

	// MaxDataReadBufSize sizes detached reads on data-bearing DataChannels.
	// Must exceed dataHeaderLen + ChunkSize plus zstd's non-compressible
	// expansion margin.
	MaxDataReadBufSize = 288 * 1024
	// MaxControlReadBufSize sizes detached reads on control DataChannels.
	// The largest frame is ADD_PEER_OFFER/ANSWER carrying a base64-encoded
	// SDP.
	MaxControlReadBufSize = 16 * 1024
)

Variables

View Source 
var (
	// ErrTruncatedFrame means the frame is shorter than its type requires.
	ErrTruncatedFrame = errors.New("truncated frame")
	// ErrUnknownFrameType means the type byte is not one of the known values.
	ErrUnknownFrameType = errors.New("unknown frame type")
)
View Source 
var ErrUnexpectedFrame = errors.New("unexpected frame")

ErrUnexpectedFrame is the sentinel returned by UnexpectedFrameHandler methods.

Functions

func AppendData 

func AppendData(dst []byte, offset uint64, payload []byte) []byte

AppendData appends a DATA frame to dst and returns the extended slice. Layout: [type:1][offset:8][payload:N]. Hot-path callers pass `buf[:0]` to reuse the backing array — pion copies the argument into its own send queue, so aliasing is safe.

func DecodeAbort 

func DecodeAbort(body []byte) string

DecodeAbort returns the reason string from an ABORT body.

func DecodeAddPeerAnswer 

func DecodeAddPeerAnswer(body []byte) (peerID uint8, sdp string, err error)

DecodeAddPeerAnswer parses an ADD_PEER_ANSWER body.

func DecodeAddPeerOffer 

func DecodeAddPeerOffer(body []byte) (peerID uint8, sdp string, err error)

DecodeAddPeerOffer parses an ADD_PEER_OFFER body.

func Dispatch 

func Dispatch(msg []byte, h FrameHandler) error

Dispatch parses one DataChannel message, decodes the body, and calls the matching method on h.

func EncodeAbort 

func EncodeAbort(reason string) []byte

EncodeAbort returns an ABORT frame with a UTF-8 reason string.

func EncodeAddPeerAnswer 

func EncodeAddPeerAnswer(peerID uint8, sdp string) []byte

EncodeAddPeerAnswer returns a complete ADD_PEER_ANSWER frame.

func EncodeAddPeerOffer 

func EncodeAddPeerOffer(peerID uint8, sdp string) []byte

EncodeAddPeerOffer returns a complete ADD_PEER_OFFER frame

func EncodeData 

func EncodeData(offset uint64, payload []byte) []byte

EncodeData returns a complete DATA frame. payload may be empty (zero-length final chunk) but is typically up to ChunkSize bytes.

func EncodeEOF 

func EncodeEOF() []byte

EncodeEOF returns a one-byte EOF frame.

func EncodeMetadata 

func EncodeMetadata(meta Metadata) []byte

EncodeMetadata returns a complete METADATA frame ready for DataChannel.Send.

Layout: [type:1][version:1][codec:1][file_size:8][sha256:32].

func EncodeTransferComplete 

func EncodeTransferComplete() []byte

EncodeTransferComplete returns a one-byte TRANSFER_COMPLETE frame.

func LabelForDataPeer 

func LabelForDataPeer(peerID int) string

LabelForDataPeer returns the DataChannel label for the peerID'th data PC in multi-PC mode (0..peers-1).

Types

type Codec 

type Codec uint8

Codec identifies how DATA payloads are encoded on the wire. 

const (
	// CodecNone means the DATA payload is raw file bytes (no compression).
	CodecNone Codec = 0x00

	// CodecZstd means each DATA payload is an independent zstd frame.
	//
	// The DATA offset is the byte position in the decompressed stream.
	CodecZstd Codec = 0x01
)

type Data 

type Data struct {
	Offset  uint64
	Payload []byte
}

Data is a decoded DATA frame.

func DecodeData 

func DecodeData(body []byte) (Data, error)

DecodeData parses the body (everything after the type byte).

Body layout: [offset:8][payload:N]. The returned Payload aliases the input slice — callers that need to keep the bytes must copy them before the owning OnMessage callback returns.

type FrameHandler 

type FrameHandler interface {
	OnMetadata(Metadata) error
	OnData(Data) error
	OnEOF() error
	OnAbort(reason string) error
	OnAddPeerOffer(peerID uint8, sdp string) error
	OnAddPeerAnswer(peerID uint8, sdp string) error
	OnTransferComplete() error
}

FrameHandler is the visitor interface Dispatch calls into. Each method corresponds to exactly one FrameType.

type FrameType 

type FrameType uint8

FrameType is the first byte of every frame. See PROTOCOL.md. 

const (
	// FrameTypeMetadata is the first frame, before any DATA
	FrameTypeMetadata FrameType = 0x01

	// FrameTypeData is the file payload with byte offset
	FrameTypeData FrameType = 0x02

	// FrameTypeEOF means the sender has no more chunks (single-PC only)
	FrameTypeEOF FrameType = 0x03

	// FrameTypeAbort is a clean-error signal with UTF-8 reason
	FrameTypeAbort FrameType = 0x04

	// FrameTypeAddPeerOffer is sender→receiver: invite a data PC by peer_id+SDP
	FrameTypeAddPeerOffer FrameType = 0x05

	// FrameTypeAddPeerAnswer is receiver→sender: answer an offer by peer_id+SDP
	FrameTypeAddPeerAnswer FrameType = 0x06

	// FrameTypeTransferComplete is sender→receiver: all data PCs flushed
	FrameTypeTransferComplete FrameType = 0x07
)

type Metadata 

type Metadata struct {
	Version  Version
	Codec    Codec
	FileSize uint64
	SHA256   [32]byte
}

Metadata is the handshake frame the sender emits before any DATA. All multi-byte fields are big-endian on the wire.

func DecodeMetadata 

func DecodeMetadata(body []byte) (Metadata, error)

DecodeMetadata parses the body (everything after the type byte).

Body layout: [version:1][codec:1][file_size:8][sha256:32].

type UnexpectedFrameHandler 

type UnexpectedFrameHandler struct{}

UnexpectedFrameHandler provides a default implementation of every FrameHandler method that returns ErrUnexpectedFrame wrapped with the frame type byte

func (UnexpectedFrameHandler) OnAbort 

func (UnexpectedFrameHandler) OnAbort(string) error

OnAbort rejects an ABORT frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnAddPeerAnswer 

func (UnexpectedFrameHandler) OnAddPeerAnswer(uint8, string) error

OnAddPeerAnswer rejects an ADD_PEER_ANSWER frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnAddPeerOffer 

func (UnexpectedFrameHandler) OnAddPeerOffer(uint8, string) error

OnAddPeerOffer rejects an ADD_PEER_OFFER frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnData 

func (UnexpectedFrameHandler) OnData(Data) error

OnData rejects a DATA frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnEOF 

func (UnexpectedFrameHandler) OnEOF() error

OnEOF rejects an EOF frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnMetadata 

func (UnexpectedFrameHandler) OnMetadata(Metadata) error

OnMetadata rejects a METADATA frame with ErrUnexpectedFrame.

func (UnexpectedFrameHandler) OnTransferComplete 

func (UnexpectedFrameHandler) OnTransferComplete() error

OnTransferComplete rejects a TRANSFER_COMPLETE frame with ErrUnexpectedFrame.

type Version 

type Version uint8

Version is the METADATA version byte. 

const (
	// ProtocolVersion is the current METADATA version byte.
	ProtocolVersion Version = 0x01
)

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.