client

Documentation

Overview

Package client is the Go-side quicrtc subscriber. It mirrors the browser receiver: open a WebTransport session to a quicrtc server, send HELLO, read SDP, then accept incoming uni feed streams and surface decoded access units one at a time.

For browser receivers, use the sibling @quicrtc/client TS package.

Index

• func DefaultClientFeatures() []string
• func NewTransport(url string, opts Options) (transport.Transport, error)
• type Client
  • func Dial(ctx context.Context, rawURL string, opts Options) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) DataChannel() *datachannel.Channel
  • func (c *Client) LastSeenSeq() map[string]uint32
  • func (c *Client) NegotiatedFeatures() []string
  • func (c *Client) Publish(ctx context.Context, lt track.LocalTrack) (Sender, error)
  • func (c *Client) ReceiveDatagram(ctx context.Context) ([]byte, error)
  • func (c *Client) Recv(ctx context.Context) (pubsub.AccessUnit, error)
  • func (c *Client) RecvOn(ctx context.Context, trackName string) (pubsub.AccessUnit, error)
  • func (c *Client) RemoteTracks() []string
  • func (c *Client) RequestKeyframe(trackName string) error
  • func (c *Client) SDP() wire.SDP
  • func (c *Client) SendBackpressure(trackName string, level uint8) error
  • func (c *Client) SendDatagram(payload []byte) error
  • func (c *Client) SessionID() string
• type Options
• type Sender

Functions

func DefaultClientFeatures

func DefaultClientFeatures() []string

DefaultClientFeatures lists every optional protocol feature this client build supports. Override Options.Features to disable specific features (e.g., for testing legacy server compatibility).

func NewTransport

func NewTransport(url string, opts Options) (transport.Transport, error)

NewTransport returns a subscriber-role native Transport. It does not dial; call Connect.

Types

type Client

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

Client is one connected subscriber.

func Dial

func Dial(ctx context.Context, rawURL string, opts Options) (*Client, error)

Dial opens a quicrtc subscriber session against rawURL. The URL fragment may carry slug=...&hash=... — if you parsed it already, pass via opts; or pass a URL with #slug=...&hash=... and we'll honor it.

func (*Client) Close

func (c *Client) Close() error

Close ends the session.

func (*Client) DataChannel

func (c *Client) DataChannel() *datachannel.Channel

DataChannel returns this client's datachannel handle.

func (*Client) LastSeenSeq

func (c *Client) LastSeenSeq() map[string]uint32

LastSeenSeq returns a snapshot of the highest sequence number this client has delivered on each track. Pass to Options.LastSeenSeq on a reconnect with the same SessionID so the server replays AUs that were in flight on the previous QUIC wire when it dropped.

func (*Client) NegotiatedFeatures

func (c *Client) NegotiatedFeatures() []string

NegotiatedFeatures returns the optional protocol features both peers agreed to use, captured from the server's SDP response. May be empty (no overlap with declared client features) or shorter than what was declared. Application code should branch on this value rather than assuming a feature is supported.

func (*Client) Publish

func (c *Client) Publish(ctx context.Context, lt track.LocalTrack) (Sender, error)

Publish creates a subscriber-side outbound track (PublishBack). The caller's Sender feeds AUs that the client streams to the server on dedicated uni QUIC streams, demuxed server-side via the same track- header convention used in the publisher direction. An Announce frame on the bidi control stream tells the server to expect the inbound track.

The returned Sender is safe for concurrent use. Closing it unannounces the track and stops the per-track pump.

func (*Client) ReceiveDatagram

func (c *Client) ReceiveDatagram(ctx context.Context) ([]byte, error)

ReceiveDatagram blocks until one datagram arrives or ctx is done. Returns the raw datagram bytes — the caller is responsible for parsing any envelope (e.g., wire.DecodeDatagram for kind-aware telemetry). Lost datagrams are not retransmitted; this API surfaces only what actually arrived.

func (*Client) Recv

func (c *Client) Recv(ctx context.Context) (pubsub.AccessUnit, error)

Recv blocks until the next access unit arrives on the implicit "primary" track. For multi-track receivers, use RecvOn(name). Returned AU.Bytes is owned by the caller.

func (*Client) RecvOn

func (c *Client) RecvOn(ctx context.Context, trackName string) (pubsub.AccessUnit, error)

RecvOn blocks until the next AccessUnit on the named track arrives. The first time a track name is seen — either via this call or via an inbound stream-header frame — its receive queue is created.

func (*Client) RemoteTracks

func (c *Client) RemoteTracks() []string

RemoteTracks returns the names of tracks the server has Announced on this session. Useful for subscribers that want to surface available tracks before the first AU arrives.

func (*Client) RequestKeyframe

func (c *Client) RequestKeyframe(trackName string) error

RequestKeyframe asks the publisher to emit a fresh keyframe on trackName NOW. Used by subscribers that detect a P-frame gap (loss event, decoder reset, or new viewer join mid-GOP) — caps the visible-stutter recovery time at ~50ms (next encoded frame) instead of waiting up to one GOP duration for the next natural keyframe.

This is the receiver-driven half of stream-per-GOP recovery: the publisher's pump already cancels-and-reopens on its own write failures; RequestKeyframe lets the subscriber trigger the same recovery when the loss is invisible from the publisher's side (e.g., quic-go retransmitted the bytes successfully but the receiver's app couldn't decode them).

Wire-piggybacks on TypeBackpressure with NeedsKeyframe=true and Level=100. v1.0 receivers ignore the boolean (it's optional JSON); v1.1+ receivers act on it by triggering OnKeyframeRequest in the publisher's session config.

func (*Client) SDP

func (c *Client) SDP() wire.SDP

SDP returns the codec advertisement received from the server.

func (*Client) SendBackpressure

func (c *Client) SendBackpressure(trackName string, level uint8) error

SendBackpressure emits a TypeBackpressure control frame so the publisher can adapt rate. Level is 0..100 (drained..full). trackName identifies the affected track (empty = session-level). Cheap; rate-limit at the application layer if needed.

func (*Client) SendDatagram

func (c *Client) SendDatagram(payload []byte) error

SendDatagram sends one unreliable QUIC datagram to the peer. Used by the kind-aware telemetry path (DeliveryDatagramOrStream) and exposed as a public API for benchmarks and apps that want fire-and-forget delivery. The payload should fit within wire.MaxDatagramPayload (1100 bytes) after envelope overhead. Returns DatagramTooLargeError from the underlying QUIC stack if the payload exceeds the path MTU.

func (*Client) SessionID

func (c *Client) SessionID() string

SessionID returns the session identifier the server allocated for this connection. Pass this value back as Options.SessionID on a reconnect to resume the session.

type Options

type Options struct {
	// CertHashB64URL pins the server's TLS cert by its SHA-256 hash
	// in browser-WebTransport format. If empty and InsecureSkipVerify
	// is false, the cert is verified against the system trust store.
	CertHashB64URL string

	// InsecureSkipVerify disables cert validation entirely. Use only
	// for tests.
	InsecureSkipVerify bool

	// Slug is the auth secret to send in HELLO. Required.
	Slug string

	// HelloTimeout caps the HELLO + SDP exchange.
	HelloTimeout time.Duration

	// SessionID, when non-empty, requests a resume of an existing
	// session. The server matches against parked sessions; if a
	// match exists, the new connection picks up the prior track
	// state and replays AUs that arrived during the disconnect.
	// Empty SessionID requests a fresh session.
	SessionID string

	// LastSeenSeq, when present, scopes the resume to a per-track
	// continuation point. For each (track name → seq) entry the
	// server replays AUs with Seq > seq from its replay buffer
	// before resuming live delivery. Recovers AUs that were in
	// flight on the QUIC wire when the previous connection dropped.
	// Pass the value returned by the prior Client.LastSeenSeq()
	// here; safe to omit (older behavior, no replay-fill).
	LastSeenSeq map[string]uint32

	// Features is the list of optional protocol features the client
	// declares support for. The server intersects this with its own
	// supported set; the result is exposed via Client.NegotiatedFeatures().
	// nil = use the defaults (every feature this client build knows
	// how to handle).
	Features []string

	// DataInboundBuffer overrides the inbound DataChannel queue depth.
	// Default 64. Bursty senders that push faster than the consumer
	// can drain (e.g., 1000+ msgs/sec batches) need a larger buffer
	// to avoid silent drops at the receive demuxer.
	DataInboundBuffer int
}

Options control client dial behavior.

type Sender

type Sender interface {
	Send(ctx context.Context, au pubsub.AccessUnit) error
	Close() error
}

Sender is the publisher-side handle for one outbound track.