Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
package protocol
import (
"encoding/json"
"errors"
"fmt"
"regexp"
)
// Role mirrors roleSchema.
type Role = string
// Roles.
const (
RoleHost Role = "host"
RoleViewer Role = "viewer"
)
// CodeEntryPolicy mirrors codeEntryPolicySchema.
type CodeEntryPolicy = string
// Code entry policies.
const (
CodeEntryOpen CodeEntryPolicy = "open"
CodeEntryPrivate CodeEntryPolicy = "private"
)
// Codec evidence patterns from viewerQualityEvidenceMetricsSchema.
var (
codecProfilePattern = regexp.MustCompile(`^[a-z0-9-]+=[a-z0-9]+$`)
codecParametersPattern = regexp.MustCompile(
`^[a-z0-9-]+=[a-z0-9]+(?:; [a-z0-9-]+=[a-z0-9]+)*$`)
audioMimeTypePattern = regexp.MustCompile(`(?i)^audio/[A-Za-z0-9.+-]{1,32}$`)
)
// Enumerations mirrored from src/shared/protocol.ts.
var (
degradationPreferences = []string{"maintain-resolution", "balanced", "maintain-framerate"}
mediaRoutePhases = []string{"prepare", "active"}
routeDemandReasons = []string{"join", "edge-unavailable", "parent-departed", "capacity-reduction", "sfu-bootstrap", "direct-convergence", "quality-convergence", "root-convergence", "publication-attach"}
routeDiagnosticFinalRoutes = []string{"direct", "sfu", "waiting", "failed"}
routeDiagnosticBuckets = []string{"none", "stale", "endpoint-capacity", "sfu-admission", "candidate-failed", "first-frame-timeout", "operation-deadline", "aborted"}
routeDiagnosticStages = []string{"admission", "first-frame", "quality-proof"}
senderQualityStates = []string{"unknown", "healthy", "degraded"}
senderQualityDegradedReasons = []string{"none", "bandwidth", "cpu"}
errorCodes = []string{"AUTH_REQUIRED", "INVALID_MESSAGE", "INVALID_TOKEN", "ROOM_ACCESS_DENIED", "ROOM_NOT_FOUND", "ROOM_FULL", "HOST_ALREADY_CONNECTED", "PEER_NOT_FOUND", "FORBIDDEN", "SERVER_ERROR"}
)
func validRevision(revision Int) bool {
return inRangeInt(revision, 0, MaxMediaRouteRevision)
}
// ---------------------------------------------------------------------------
// mediaRouteUpstreamSchema
// ---------------------------------------------------------------------------
// MediaRouteUpstream mirrors mediaRouteUpstreamSchema.
type MediaRouteUpstream struct {
Kind string `json:"kind"`
PeerID string `json:"peerId,omitempty"`
}
// NoUpstream builds { kind: "none" }.
func NoUpstream() MediaRouteUpstream { return MediaRouteUpstream{Kind: "none"} }
// PeerUpstream builds { kind: "peer", peerId }.
func PeerUpstream(peerID string) MediaRouteUpstream {
return MediaRouteUpstream{Kind: "peer", PeerID: peerID}
}
// SfuUpstream builds { kind: "sfu" }.
func SfuUpstream() MediaRouteUpstream { return MediaRouteUpstream{Kind: "sfu"} }
// UnmarshalJSON implements json.Unmarshaler.
func (v *MediaRouteUpstream) UnmarshalJSON(data []byte) error {
*v = MediaRouteUpstream{}
type raw MediaRouteUpstream
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("kind"); err != nil {
return err
}
switch v.Kind {
case "none", "sfu":
if present.has("peerId") {
return fmt.Errorf("upstream %q must not carry peerId", v.Kind)
}
case "peer":
if err := present.require("peerId"); err != nil {
return err
}
if !ValidOpaqueID(v.PeerID) {
return errors.New("upstream peerId is not an opaque id")
}
default:
return fmt.Errorf("unknown upstream kind %q", v.Kind)
}
return nil
}
// ---------------------------------------------------------------------------
// qualitySettingsSchema / routePolicySchema / runtimeCapabilitiesSchema
// ---------------------------------------------------------------------------
// QualityResolution is a requested ceiling, not encoder availability or an allocation.
type QualityResolution struct {
Width Int `json:"width"`
Height Int `json:"height"`
}
func (v *QualityResolution) UnmarshalJSON(data []byte) error {
*v = QualityResolution{}
type raw QualityResolution
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("width", "height"); err != nil {
return err
}
if !inRangeInt(v.Width, 1, 0xffff_ffff) || !inRangeInt(v.Height, 1, 0xffff_ffff) {
return errors.New("resolution is out of range")
}
return nil
}
// QualitySettings mirrors qualitySettingsSchema.
type QualitySettings struct {
Resolution QualityResolution `json:"resolution"`
MaxFramerate Num `json:"maxFramerate"`
MaxBitrate Int `json:"maxBitrate"`
DegradationPreference string `json:"degradationPreference"`
MaxAudioBitrate Int `json:"maxAudioBitrate,omitempty"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *QualitySettings) UnmarshalJSON(data []byte) error {
*v = QualitySettings{}
type raw QualitySettings
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require(
"resolution", "maxFramerate", "maxBitrate", "degradationPreference"); err != nil {
return err
}
if err := present.optional("maxAudioBitrate"); err != nil {
return err
}
if v.MaxFramerate <= 0 || !inRangeNum(v.MaxFramerate, 0, MaxSafeInteger) {
return errors.New("maxFramerate is out of range")
}
if !inRangeInt(v.MaxBitrate, 1, 0xffff_ffff) {
return errors.New("maxBitrate is out of range")
}
if !enumOf(v.DegradationPreference, degradationPreferences...) {
return fmt.Errorf("unknown degradationPreference %q", v.DegradationPreference)
}
if present.has("maxAudioBitrate") && !inRangeInt(v.MaxAudioBitrate, MinAudioBitrate, MaxAudioBitrate) {
return errors.New("maxAudioBitrate is out of range")
}
return nil
}
// RoutePolicy mirrors routePolicySchema.
type RoutePolicy struct {
PeerOnly bool `json:"peerOnly"`
TopologyOptimization bool `json:"topologyOptimization"`
NatPrediction bool `json:"natPrediction"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RoutePolicy) UnmarshalJSON(data []byte) error {
*v = RoutePolicy{}
type raw RoutePolicy
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
return present.require("peerOnly", "topologyOptimization", "natPrediction")
}
// RuntimeCapabilities mirrors runtimeCapabilitiesSchema.
type RuntimeCapabilities struct {
Sfu bool `json:"sfu"`
SfuOnly bool `json:"sfuOnly,omitempty"`
NatPrediction bool `json:"natPrediction"`
RoomInteractions bool `json:"roomInteractions,omitempty"`
RoomVoice bool `json:"roomVoice,omitempty"`
RoomVoiceListeningPresence bool `json:"roomVoiceListeningPresence,omitempty"`
RoomVoiceBitrate bool `json:"roomVoiceBitrate,omitempty"`
RelayVolunteer bool `json:"relayVolunteer,omitempty"`
HostRoomSession bool `json:"hostRoomSession,omitempty"`
RemoteInput bool `json:"remoteInput,omitempty"`
ViewerRouteSelection bool `json:"viewerRouteSelection,omitempty"`
AudioPresence bool `json:"audioPresence,omitempty"`
CoPlayPresence bool `json:"coPlayPresence,omitempty"`
RoomReactionIDs []string `json:"roomReactionIds,omitempty"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RuntimeCapabilities) UnmarshalJSON(data []byte) error {
*v = RuntimeCapabilities{}
var present fields
if err := json.Unmarshal(data, &present); err != nil {
return err
}
if present == nil {
return errors.New("runtime capabilities must be an object")
}
if err := present.optional("sfu", "sfuOnly", "roomInteractions", "roomVoice", "roomVoiceListeningPresence", "roomVoiceBitrate", "relayVolunteer", "hostRoomSession", "natPrediction", "remoteInput", "viewerRouteSelection", "audioPresence", "coPlayPresence", "roomReactionIds"); err != nil {
return err
}
for key, target := range map[string]*bool{
"sfu": &v.Sfu, "sfuOnly": &v.SfuOnly, "natPrediction": &v.NatPrediction,
"roomInteractions": &v.RoomInteractions, "hostRoomSession": &v.HostRoomSession,
"roomVoice": &v.RoomVoice,
"roomVoiceListeningPresence": &v.RoomVoiceListeningPresence,
"roomVoiceBitrate": &v.RoomVoiceBitrate,
"relayVolunteer": &v.RelayVolunteer,
"remoteInput": &v.RemoteInput,
"viewerRouteSelection": &v.ViewerRouteSelection,
"audioPresence": &v.AudioPresence,
"coPlayPresence": &v.CoPlayPresence,
} {
if value, ok := present[key]; ok {
if err := json.Unmarshal(value, target); err != nil {
return err
}
}
}
if value, ok := present["roomReactionIds"]; ok {
if err := json.Unmarshal(value, &v.RoomReactionIDs); err != nil {
return err
}
if len(v.RoomReactionIDs) > 64 {
return errors.New("too many room reaction identifiers")
}
for _, id := range v.RoomReactionIDs {
if !reactionIDPattern.MatchString(id) {
return errors.New("invalid room reaction identifier")
}
}
}
return nil
}
// ---------------------------------------------------------------------------
// iceConfigSchema
// ---------------------------------------------------------------------------
// IceServerURLs mirrors z.union([stunUrlSchema, z.array(stunUrlSchema)]).
type IceServerURLs struct {
Single string
List []string
}
// IceServerURLList builds the array form.
func IceServerURLList(urls ...string) IceServerURLs {
if urls == nil {
urls = []string{}
}
return IceServerURLs{List: urls}
}
// MarshalJSON implements json.Marshaler.
func (v IceServerURLs) MarshalJSON() ([]byte, error) {
if v.List != nil {
return marshalJSON(v.List)
}
return marshalJSON(v.Single)
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *IceServerURLs) UnmarshalJSON(data []byte) error {
*v = IceServerURLs{}
if len(data) > 0 && data[0] == '[' {
var list []string
if err := json.Unmarshal(data, &list); err != nil {
return err
}
if len(list) < 1 || len(list) > MaxIceServerURLs {
return errors.New("iceServers[].urls length is out of range")
}
for _, url := range list {
if !ValidStunURLValue(url) {
return errors.New("Invalid STUN URL")
}
}
v.List = list
return nil
}
var single string
if err := json.Unmarshal(data, &single); err != nil {
return err
}
if !ValidStunURLValue(single) {
return errors.New("Invalid STUN URL")
}
v.Single = single
return nil
}
// ValidStunURLValue mirrors stunUrlSchema: 1..512 UTF-16 code units plus
// isValidStunUrl. It is the single owner of that bound; config validates
// STUN_URLS and the Client's local STUN list through it.
func ValidStunURLValue(value string) bool {
length := UTF16Length(value)
return length >= 1 && length <= MaxStunURLLength && ValidStunURL(value)
}
// IceServer mirrors iceServerSchema.
type IceServer struct {
URLs IceServerURLs `json:"urls"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *IceServer) UnmarshalJSON(data []byte) error {
*v = IceServer{}
type raw IceServer
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
return present.require("urls")
}
// IceConfig mirrors iceConfigSchema.
type IceConfig struct {
IceServers []IceServer `json:"iceServers"`
NatPredictionStunURLs []string `json:"natPredictionStunUrls"`
}
// MarshalJSON implements json.Marshaler.
func (v IceConfig) MarshalJSON() ([]byte, error) {
type raw IceConfig
value := raw(v)
if value.IceServers == nil {
value.IceServers = []IceServer{}
}
if value.NatPredictionStunURLs == nil {
value.NatPredictionStunURLs = []string{}
}
return marshalJSON(value)
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *IceConfig) UnmarshalJSON(data []byte) error {
*v = IceConfig{}
type raw IceConfig
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("iceServers", "natPredictionStunUrls"); err != nil {
return err
}
if len(v.IceServers) > 8 {
return errors.New("iceServers holds too many entries")
}
if len(v.NatPredictionStunURLs) > MaxNatPredictionAuxiliaryStunURLs {
return errors.New("natPredictionStunUrls holds too many entries")
}
for _, url := range v.NatPredictionStunURLs {
if !ValidStunURLValue(url) {
return errors.New("Invalid STUN URL")
}
}
return nil
}
// ---------------------------------------------------------------------------
// signalPayloadSchema
// ---------------------------------------------------------------------------
// SessionDescription mirrors sessionDescriptionSchema.
type SessionDescription struct {
Type string `json:"type"`
SDP string `json:"sdp"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *SessionDescription) UnmarshalJSON(data []byte) error {
*v = SessionDescription{}
type raw SessionDescription
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("type", "sdp"); err != nil {
return err
}
if !enumOf(v.Type, "offer", "answer") {
return fmt.Errorf("unknown description type %q", v.Type)
}
if length := UTF16Length(v.SDP); length < 1 || length > 48*1024 {
return errors.New("sdp length is out of range")
}
return nil
}
// IceCandidate mirrors iceCandidateSchema.
type IceCandidate struct {
Candidate string `json:"candidate"`
SDPMid Nullable[string] `json:"sdpMid,omitzero"`
SDPMLineIndex Nullable[Int] `json:"sdpMLineIndex,omitzero"`
UsernameFragment Nullable[string] `json:"usernameFragment,omitzero"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *IceCandidate) UnmarshalJSON(data []byte) error {
*v = IceCandidate{}
type raw IceCandidate
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("candidate"); err != nil {
return err
}
if UTF16Length(v.Candidate) > 4096 {
return errors.New("candidate is too long")
}
if v.SDPMid.Value != nil && UTF16Length(*v.SDPMid.Value) > 128 {
return errors.New("sdpMid is too long")
}
if v.SDPMLineIndex.Value != nil && !inRangeInt(*v.SDPMLineIndex.Value, 0, 255) {
return errors.New("sdpMLineIndex is out of range")
}
if v.UsernameFragment.Value != nil && UTF16Length(*v.UsernameFragment.Value) > 256 {
return errors.New("usernameFragment is too long")
}
return nil
}
// SignalPayload mirrors signalPayloadSchema. Candidate is nil for the JSON
// null the "candidate" variant requires.
type SignalPayload struct {
Kind string
ConnectionID string
Description *SessionDescription
Candidate *IceCandidate
Punch *PunchSignal
Punched bool
}
// MarshalJSON implements json.Marshaler.
func (v SignalPayload) MarshalJSON() ([]byte, error) {
if v.Kind == "punch" {
return marshalJSON(struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Punch *PunchSignal `json:"punch"`
}{v.Kind, v.ConnectionID, v.Punch})
}
if v.Kind == "description" {
return marshalJSON(struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Description *SessionDescription `json:"description"`
Punched bool `json:"punched,omitempty"`
}{v.Kind, v.ConnectionID, v.Description, v.Punched})
}
return marshalJSON(struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Candidate *IceCandidate `json:"candidate"`
}{v.Kind, v.ConnectionID, v.Candidate})
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *SignalPayload) UnmarshalJSON(data []byte) error {
*v = SignalPayload{}
kind, err := typeOf(data, "kind")
if err != nil {
return err
}
switch kind {
case "punch":
var body struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Punch *PunchSignal `json:"punch"`
}
present, err := decodeObject(data, &body)
if err != nil {
return err
}
if err = present.require("kind", "connectionId", "punch"); err != nil {
return err
}
if !ValidOpaqueID(body.ConnectionID) || body.Punch == nil {
return errors.New("invalid connection preparation signal")
}
*v = SignalPayload{Kind: kind, ConnectionID: body.ConnectionID, Punch: body.Punch}
return nil
case "description":
var body struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Description *SessionDescription `json:"description"`
Punched bool `json:"punched,omitempty"`
}
present, err := decodeObject(data, &body)
if err != nil {
return err
}
if err := present.require("kind", "connectionId", "description"); err != nil {
return err
}
if !ValidOpaqueID(body.ConnectionID) {
return errors.New("connectionId is not an opaque id")
}
if _, exists := present["punched"]; exists && !body.Punched {
return errors.New("punched must be true when present")
}
*v = SignalPayload{Kind: kind, ConnectionID: body.ConnectionID, Description: body.Description, Punched: body.Punched}
return nil
case "candidate":
var body struct {
Kind string `json:"kind"`
ConnectionID string `json:"connectionId"`
Candidate *IceCandidate `json:"candidate"`
}
present, err := decodeObject(data, &body)
if err != nil {
return err
}
if err := present.require("kind", "connectionId"); err != nil {
return err
}
if err := present.requireNullable("candidate"); err != nil {
return err
}
if !ValidOpaqueID(body.ConnectionID) {
return errors.New("connectionId is not an opaque id")
}
*v = SignalPayload{Kind: kind, ConnectionID: body.ConnectionID, Candidate: body.Candidate}
return nil
}
return fmt.Errorf("unknown signal payload kind %q", kind)
}
// ---------------------------------------------------------------------------
// preparedRouteCandidateSchema / participantRouteAssignmentSchema
// ---------------------------------------------------------------------------
// ConnectionAttempt mirrors preparedRouteCandidateSchema.connectionAttempt.
type ConnectionAttempt struct {
Current Int `json:"current"`
Total Int `json:"total"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *ConnectionAttempt) UnmarshalJSON(data []byte) error {
*v = ConnectionAttempt{}
type raw ConnectionAttempt
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("current", "total"); err != nil {
return err
}
if !inRangeInt(v.Current, 1, int64(v.Total)) {
return errors.New("connectionAttempt.current is out of range")
}
if !inRangeInt(v.Total, 1, MaxSafeInteger) {
return errors.New("connectionAttempt.total is out of range")
}
return nil
}
// PreparedRouteCandidate mirrors preparedRouteCandidateSchema.
type PreparedRouteCandidate struct {
ChildPeerID string `json:"childPeerId"`
ConnectionID string `json:"connectionId"`
Transport string `json:"transport"`
QualityProbe bool `json:"qualityProbe"`
ConnectionAttempt *ConnectionAttempt `json:"connectionAttempt,omitempty"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *PreparedRouteCandidate) UnmarshalJSON(data []byte) error {
*v = PreparedRouteCandidate{}
type raw PreparedRouteCandidate
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require(
"childPeerId", "connectionId", "transport", "qualityProbe"); err != nil {
return err
}
if err := present.optional("connectionAttempt"); err != nil {
return err
}
if !ValidOpaqueID(v.ChildPeerID) || !ValidOpaqueID(v.ConnectionID) {
return errors.New("prepared route candidate ids are not opaque ids")
}
if !enumOf(v.Transport, "direct", "sfu") {
return fmt.Errorf("unknown transport %q", v.Transport)
}
return nil
}
// ParticipantRouteAssignment mirrors participantRouteAssignmentSchema.
type ParticipantRouteAssignment struct {
Upstream MediaRouteUpstream `json:"upstream"`
ChildPeerIDs []string `json:"childPeerIds"`
SfuPublicationGeneration *string `json:"sfuPublicationGeneration"`
}
// MarshalJSON implements json.Marshaler.
func (v ParticipantRouteAssignment) MarshalJSON() ([]byte, error) {
type raw ParticipantRouteAssignment
value := raw(v)
if value.ChildPeerIDs == nil {
value.ChildPeerIDs = []string{}
}
return marshalJSON(value)
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *ParticipantRouteAssignment) UnmarshalJSON(data []byte) error {
*v = ParticipantRouteAssignment{}
type raw ParticipantRouteAssignment
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("upstream", "childPeerIds"); err != nil {
return err
}
if err := present.requireNullable("sfuPublicationGeneration"); err != nil {
return err
}
if len(v.ChildPeerIDs) > MaxViewersPerRoomLimit {
return errors.New("childPeerIds holds too many entries")
}
seen := make(map[string]struct{}, len(v.ChildPeerIDs))
for _, peerID := range v.ChildPeerIDs {
if !ValidOpaqueID(peerID) {
return errors.New("childPeerIds holds a non-opaque id")
}
if _, duplicate := seen[peerID]; duplicate {
return errors.New("childPeerIds must be unique")
}
seen[peerID] = struct{}{}
}
if v.SfuPublicationGeneration != nil && !ValidOpaqueID(*v.SfuPublicationGeneration) {
return errors.New("sfuPublicationGeneration is not an opaque id")
}
// superRefine: an SFU upstream requires its publication generation and a
// peer upstream cannot own one.
if v.Upstream.Kind == "sfu" && v.SfuPublicationGeneration == nil {
return errors.New("An SFU upstream requires its publication generation")
}
if v.Upstream.Kind == "peer" && v.SfuPublicationGeneration != nil {
return errors.New("A peer upstream cannot own an SFU publication generation")
}
return nil
}
// ---------------------------------------------------------------------------
// routeDiagnosticSnapshotSchema
// ---------------------------------------------------------------------------
// RouteDiagnosticParent mirrors routeDiagnosticParentSchema.
type RouteDiagnosticParent struct {
Kind string `json:"kind"`
Ordinal Int `json:"ordinal,omitempty"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RouteDiagnosticParent) UnmarshalJSON(data []byte) error {
*v = RouteDiagnosticParent{}
type raw RouteDiagnosticParent
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("kind"); err != nil {
return err
}
switch v.Kind {
case "none", "host", "sfu":
if present.has("ordinal") {
return fmt.Errorf("route diagnostic parent %q must not carry ordinal", v.Kind)
}
case "viewer":
if err := present.require("ordinal"); err != nil {
return err
}
if !inRangeInt(v.Ordinal, 1, MaxViewersPerRoomLimit) {
return errors.New("route diagnostic parent ordinal is out of range")
}
default:
return fmt.Errorf("unknown route diagnostic parent kind %q", v.Kind)
}
return nil
}
// RouteDiagnosticQuality mirrors routeDiagnosticQualitySchema.
type RouteDiagnosticQuality struct {
EligibleWindows Int `json:"eligibleWindows"`
EligibleDurationMs Int `json:"eligibleDurationMs"`
FreezeWindows Int `json:"freezeWindows"`
FreezeCount Int `json:"freezeCount"`
FreezeDurationMs Int `json:"freezeDurationMs"`
PauseCount Int `json:"pauseCount"`
PauseDurationMs Int `json:"pauseDurationMs"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RouteDiagnosticQuality) UnmarshalJSON(data []byte) error {
*v = RouteDiagnosticQuality{}
type raw RouteDiagnosticQuality
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("eligibleWindows", "eligibleDurationMs", "freezeWindows",
"freezeCount", "freezeDurationMs", "pauseCount", "pauseDurationMs"); err != nil {
return err
}
for _, value := range []Int{v.EligibleWindows, v.EligibleDurationMs, v.FreezeWindows,
v.FreezeCount, v.FreezeDurationMs, v.PauseCount, v.PauseDurationMs} {
if !inRangeInt(value, 0, MaxSafeInteger) {
return errors.New("route diagnostic quality value is out of range")
}
}
return nil
}
// RouteDiagnosticChild mirrors routeDiagnosticChildSchema.
type RouteDiagnosticChild struct {
Ordinal Int `json:"ordinal"`
Parent RouteDiagnosticParent `json:"parent"`
EffectiveCapacity Int `json:"effectiveCapacity"`
ChildCount Int `json:"childCount"`
DemandAgeMs *Int `json:"demandAgeMs"`
QueueWaitMs *Int `json:"queueWaitMs"`
CandidateStartMs *Int `json:"candidateStartMs"`
FirstDecodedFrameMs *Int `json:"firstDecodedFrameMs"`
FinalMs *Int `json:"finalMs"`
FinalRoute string `json:"finalRoute"`
RejectionBucket string `json:"rejectionBucket"`
Quality *RouteDiagnosticQuality `json:"quality"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RouteDiagnosticChild) UnmarshalJSON(data []byte) error {
*v = RouteDiagnosticChild{}
type raw RouteDiagnosticChild
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("ordinal", "parent", "effectiveCapacity", "childCount",
"finalRoute", "rejectionBucket"); err != nil {
return err
}
if err := present.requireNullable("demandAgeMs", "queueWaitMs", "candidateStartMs",
"firstDecodedFrameMs", "finalMs", "quality"); err != nil {
return err
}
if !inRangeInt(v.Ordinal, 1, MaxViewersPerRoomLimit) {
return errors.New("route diagnostic ordinal is out of range")
}
if !inRangeInt(v.EffectiveCapacity, 0, MaxViewersPerRoomLimit) ||
!inRangeInt(v.ChildCount, 0, MaxViewersPerRoomLimit) {
return errors.New("route diagnostic capacity is out of range")
}
for _, duration := range []*Int{v.DemandAgeMs, v.QueueWaitMs, v.CandidateStartMs,
v.FirstDecodedFrameMs, v.FinalMs} {
if duration != nil && !inRangeInt(*duration, 0, MaxSafeInteger) {
return errors.New("route diagnostic duration is out of range")
}
}
if !enumOf(v.FinalRoute, routeDiagnosticFinalRoutes...) {
return fmt.Errorf("unknown finalRoute %q", v.FinalRoute)
}
if !enumOf(v.RejectionBucket, routeDiagnosticBuckets...) {
return fmt.Errorf("unknown rejectionBucket %q", v.RejectionBucket)
}
return nil
}
// RouteDiagnosticOperation mirrors routeDiagnosticOperationSchema.
type RouteDiagnosticOperation struct {
ChildOrdinal Int `json:"childOrdinal"`
Reason string `json:"reason"`
Stage string `json:"stage"`
Cursor Int `json:"cursor"`
CandidateCount Int `json:"candidateCount"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RouteDiagnosticOperation) UnmarshalJSON(data []byte) error {
*v = RouteDiagnosticOperation{}
type raw RouteDiagnosticOperation
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require(
"childOrdinal", "reason", "stage", "cursor", "candidateCount"); err != nil {
return err
}
if !inRangeInt(v.ChildOrdinal, 1, MaxViewersPerRoomLimit) {
return errors.New("route diagnostic childOrdinal is out of range")
}
if !enumOf(v.Reason, routeDemandReasons...) {
return fmt.Errorf("unknown route demand reason %q", v.Reason)
}
if !enumOf(v.Stage, routeDiagnosticStages...) {
return fmt.Errorf("unknown route diagnostic stage %q", v.Stage)
}
if !inRangeInt(v.Cursor, 0, MaxViewersPerRoomLimit) {
return errors.New("route diagnostic cursor is out of range")
}
if !inRangeInt(v.CandidateCount, 1, MaxViewersPerRoomLimit+1) {
return errors.New("route diagnostic candidateCount is out of range")
}
return nil
}
// RouteDiagnosticSnapshot mirrors routeDiagnosticSnapshotSchema.
type RouteDiagnosticSnapshot struct {
Children []RouteDiagnosticChild `json:"children"`
Operation *RouteDiagnosticOperation `json:"operation"`
}
// MarshalJSON implements json.Marshaler.
func (v RouteDiagnosticSnapshot) MarshalJSON() ([]byte, error) {
type raw RouteDiagnosticSnapshot
value := raw(v)
if value.Children == nil {
value.Children = []RouteDiagnosticChild{}
}
return marshalJSON(value)
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *RouteDiagnosticSnapshot) UnmarshalJSON(data []byte) error {
*v = RouteDiagnosticSnapshot{}
type raw RouteDiagnosticSnapshot
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("children"); err != nil {
return err
}
if err := present.requireNullable("operation"); err != nil {
return err
}
if len(v.Children) > MaxViewersPerRoomLimit {
return errors.New("route diagnostic snapshot holds too many children")
}
// superRefine: unique ordinals, resolvable viewer parents, and an
// operation that names a present child with a cursor inside its candidates.
ordinals := make(map[Int]struct{}, len(v.Children))
for _, child := range v.Children {
ordinals[child.Ordinal] = struct{}{}
}
if len(ordinals) != len(v.Children) {
return errors.New("Route diagnostic ordinals must be unique")
}
for _, child := range v.Children {
if child.Parent.Kind != "viewer" {
continue
}
if _, ok := ordinals[child.Parent.Ordinal]; !ok || child.Parent.Ordinal == child.Ordinal {
return errors.New("Route diagnostic parent ordinal is invalid")
}
}
if v.Operation != nil {
if _, ok := ordinals[v.Operation.ChildOrdinal]; !ok ||
v.Operation.Cursor >= v.Operation.CandidateCount {
return errors.New("Route diagnostic operation is invalid")
}
}
return nil
}
// ---------------------------------------------------------------------------
// participantPresenceEntrySchema
// ---------------------------------------------------------------------------
// ParticipantPresenceEntry mirrors participantPresenceEntrySchema. The viewer
// variant is viewerPresenceEntrySchema.
type ParticipantPresenceEntry struct {
Role Role `json:"role"`
PeerID string `json:"peerId"`
DisplayName DisplayName `json:"displayName"`
Upstream MediaRouteUpstream `json:"upstream"`
MediaReady bool `json:"mediaReady,omitempty"`
}
// HostPresenceEntry builds the host entry, whose upstream is always
// { kind: "none" } and which never carries mediaReady.
func HostPresenceEntry(peerID string, displayName DisplayName) ParticipantPresenceEntry {
return ParticipantPresenceEntry{
Role: RoleHost, PeerID: peerID, DisplayName: displayName, Upstream: NoUpstream(),
}
}
// NewViewerPresenceEntry builds a viewer entry; mediaReady is emitted only
// when true, matching `...(mediaReady ? { mediaReady: true } : {})`.
func NewViewerPresenceEntry(
peerID string, displayName DisplayName, upstream MediaRouteUpstream, mediaReady bool,
) ParticipantPresenceEntry {
return ParticipantPresenceEntry{
Role: RoleViewer, PeerID: peerID, DisplayName: displayName,
Upstream: upstream, MediaReady: mediaReady,
}
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *ParticipantPresenceEntry) UnmarshalJSON(data []byte) error {
*v = ParticipantPresenceEntry{}
type raw ParticipantPresenceEntry
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("role", "peerId", "displayName", "upstream"); err != nil {
return err
}
if !ValidOpaqueID(v.PeerID) {
return errors.New("presence peerId is not an opaque id")
}
switch v.Role {
case RoleHost:
if present.has("mediaReady") {
return errors.New("host presence must not carry mediaReady")
}
if v.Upstream.Kind != "none" {
return errors.New("host presence upstream must be none")
}
case RoleViewer:
if err := present.optional("mediaReady"); err != nil {
return err
}
if present.has("mediaReady") && !v.MediaReady {
return errors.New("mediaReady must be true when present")
}
default:
return fmt.Errorf("unknown presence role %q", v.Role)
}
return nil
}
// ---------------------------------------------------------------------------
// viewerQualityEvidenceMetricsSchema / senderQualityDiagnosticsSchema
// ---------------------------------------------------------------------------
// ViewerQualityEvidenceGuard mirrors viewerQualityEvidenceGuardSchema.
type ViewerQualityEvidenceGuard struct {
ConnectionID string `json:"connectionId"`
RouteRevision Int `json:"routeRevision"`
PresentationEpoch Int `json:"presentationEpoch"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *ViewerQualityEvidenceGuard) UnmarshalJSON(data []byte) error {
*v = ViewerQualityEvidenceGuard{}
type raw ViewerQualityEvidenceGuard
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("connectionId", "routeRevision", "presentationEpoch"); err != nil {
return err
}
if !ValidOpaqueID(v.ConnectionID) {
return errors.New("guard connectionId is not an opaque id")
}
if !validRevision(v.RouteRevision) {
return errors.New("guard routeRevision is out of range")
}
if !inRangeInt(v.PresentationEpoch, 0, MaxSafeInteger) {
return errors.New("guard presentationEpoch is out of range")
}
return nil
}
// ViewerQualityEvidenceMetrics mirrors viewerQualityEvidenceMetricsSchema.
type ViewerQualityEvidenceMetrics struct {
NatTraversalPath string `json:"natTraversalPath"`
Width *Int `json:"width"`
Height *Int `json:"height"`
FramesPerSecond *Num `json:"framesPerSecond"`
BitrateKbps *Num `json:"bitrateKbps"`
PacketsReceivedDelta *Int `json:"packetsReceivedDelta"`
PacketsLostDelta *Int `json:"packetsLostDelta"`
RttMs *Num `json:"rttMs"`
JitterMs *Num `json:"jitterMs"`
FramesDecodedDelta *Int `json:"framesDecodedDelta"`
FramesDroppedDelta *Int `json:"framesDroppedDelta"`
DecodeMsPerFrame *Num `json:"decodeMsPerFrame"`
FreezeCountDelta *Int `json:"freezeCountDelta"`
FreezeDurationMsDelta *Num `json:"freezeDurationMsDelta"`
PauseCountDelta *Int `json:"pauseCountDelta"`
PauseDurationMsDelta *Num `json:"pauseDurationMsDelta"`
Codec *string `json:"codec"`
CodecProfile *string `json:"codecProfile"`
CodecParameters *string `json:"codecParameters"`
AudioBitrateKbps *Num `json:"audioBitrateKbps"`
AudioPacketLossPercent *Num `json:"audioPacketLossPercent"`
AudioJitterMs *Num `json:"audioJitterMs"`
AudioVideoPlayoutDeltaMs *Num `json:"audioVideoPlayoutDeltaMs"`
VideoJitterBufferDelayMs *Num `json:"videoJitterBufferDelayMs"`
AudioJitterBufferDelayMs *Num `json:"audioJitterBufferDelayMs"`
AudioConcealedSamplesPercent *Num `json:"audioConcealedSamplesPercent"`
AudioConcealmentEventsDelta *Int `json:"audioConcealmentEventsDelta"`
AudioCodec *string `json:"audioCodec"`
}
var viewerQualityEvidenceMetricKeys = []string{
"natTraversalPath", "width", "height", "framesPerSecond", "bitrateKbps",
"packetsReceivedDelta", "packetsLostDelta", "rttMs", "jitterMs",
"framesDecodedDelta", "framesDroppedDelta", "decodeMsPerFrame",
"freezeCountDelta", "freezeDurationMsDelta", "pauseCountDelta",
"pauseDurationMsDelta", "codec", "codecProfile", "codecParameters",
"audioBitrateKbps", "audioPacketLossPercent", "audioJitterMs",
"audioVideoPlayoutDeltaMs", "videoJitterBufferDelayMs",
"audioJitterBufferDelayMs", "audioConcealedSamplesPercent",
"audioConcealmentEventsDelta", "audioCodec",
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *ViewerQualityEvidenceMetrics) UnmarshalJSON(data []byte) error {
*v = ViewerQualityEvidenceMetrics{}
type raw ViewerQualityEvidenceMetrics
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.requireNullable(viewerQualityEvidenceMetricKeys...); err != nil {
return err
}
if err := present.require("natTraversalPath"); err != nil {
return err
}
if !enumOf(v.NatTraversalPath, NatTraversalPaths[:]...) {
return fmt.Errorf("unknown natTraversalPath %q", v.NatTraversalPath)
}
for _, bound := range []struct {
value *Int
minimum, maximum int64
}{
{v.Width, 1, MaxSafeInteger}, {v.Height, 1, MaxSafeInteger},
{v.PacketsReceivedDelta, 0, MaxSafeInteger}, {v.PacketsLostDelta, 0, MaxSafeInteger},
{v.FramesDecodedDelta, 0, MaxSafeInteger}, {v.FramesDroppedDelta, 0, MaxSafeInteger},
{v.FreezeCountDelta, 0, MaxSafeInteger}, {v.PauseCountDelta, 0, MaxSafeInteger},
{v.AudioConcealmentEventsDelta, 0, MaxSafeInteger},
} {
if bound.value != nil && !inRangeInt(*bound.value, bound.minimum, bound.maximum) {
return errors.New("viewer quality evidence integer is out of range")
}
}
for _, bound := range []struct {
value *Num
minimum, maximum float64
}{
{v.FramesPerSecond, 0, MaxSafeInteger}, {v.BitrateKbps, 0, MaxSafeInteger},
{v.RttMs, 0, MaxSafeInteger}, {v.JitterMs, 0, MaxSafeInteger},
{v.DecodeMsPerFrame, 0, MaxSafeInteger},
{v.FreezeDurationMsDelta, 0, MaxSafeInteger},
{v.PauseDurationMsDelta, 0, MaxSafeInteger},
{v.AudioBitrateKbps, 0, MaxSafeInteger}, {v.AudioPacketLossPercent, 0, 100},
{v.AudioJitterMs, 0, MaxSafeInteger},
{v.AudioVideoPlayoutDeltaMs, -MaxSafeInteger, MaxSafeInteger},
{v.VideoJitterBufferDelayMs, 0, MaxSafeInteger}, {v.AudioJitterBufferDelayMs, 0, MaxSafeInteger},
{v.AudioConcealedSamplesPercent, 0, 100},
} {
if bound.value != nil && !inRangeNum(*bound.value, bound.minimum, bound.maximum) {
return errors.New("viewer quality evidence number is out of range")
}
}
if v.Codec != nil && (UTF16Length(*v.Codec) > 64 || !videoMimeTypePattern.MatchString(*v.Codec)) {
return errors.New("codec is not a video mime type")
}
if v.CodecProfile != nil &&
(UTF16Length(*v.CodecProfile) > 64 || !codecProfilePattern.MatchString(*v.CodecProfile)) {
return errors.New("codecProfile is malformed")
}
if v.CodecParameters != nil &&
(UTF16Length(*v.CodecParameters) > 128 ||
!codecParametersPattern.MatchString(*v.CodecParameters)) {
return errors.New("codecParameters is malformed")
}
if v.AudioCodec != nil &&
(UTF16Length(*v.AudioCodec) > 64 || !audioMimeTypePattern.MatchString(*v.AudioCodec)) {
return errors.New("audioCodec is not an audio mime type")
}
// refine: dimensions travel together.
if (v.Width == nil) != (v.Height == nil) {
return errors.New("Viewer quality dimensions must be present together")
}
// refine: codec evidence must be canonical.
if !IsCanonicalVideoCodecEvidence(
derefString(v.Codec), derefString(v.CodecProfile), derefString(v.CodecParameters)) {
return errors.New("Viewer codec evidence is not canonical")
}
return nil
}
func derefString(value *string) string {
if value == nil {
return ""
}
return *value
}
// SenderQualityDiagnostics mirrors senderQualityDiagnosticsSchema.
type SenderQualityDiagnostics struct {
NatTraversalPath string `json:"natTraversalPath"`
Reason *string `json:"reason"`
FramesPerSecond *Num `json:"framesPerSecond"`
BitrateKbps *Num `json:"bitrateKbps"`
CaptureFramesPerSecond Nullable[Num] `json:"captureFramesPerSecond,omitzero"`
MediaSourceFramesPerSecond Nullable[Num] `json:"mediaSourceFramesPerSecond,omitzero"`
Width Nullable[Int] `json:"width,omitzero"`
Height Nullable[Int] `json:"height,omitzero"`
VideoEncodingCount Nullable[Int] `json:"videoEncodingCount,omitzero"`
ActiveVideoEncodingCount Nullable[Int] `json:"activeVideoEncodingCount,omitzero"`
AvailableOutgoingKbps Nullable[Num] `json:"availableOutgoingKbps,omitzero"`
RttMs Nullable[Num] `json:"rttMs,omitzero"`
PacketLossPercent Nullable[Num] `json:"packetLossPercent,omitzero"`
}
// UnmarshalJSON implements json.Unmarshaler.
func (v *SenderQualityDiagnostics) UnmarshalJSON(data []byte) error {
*v = SenderQualityDiagnostics{}
type raw SenderQualityDiagnostics
present, err := decodeObject(data, (*raw)(v))
if err != nil {
return err
}
if err := present.require("natTraversalPath"); err != nil {
return err
}
if err := present.requireNullable(
"reason", "framesPerSecond", "bitrateKbps"); err != nil {
return err
}
if !enumOf(v.NatTraversalPath, NatTraversalPaths[:]...) {
return fmt.Errorf("unknown natTraversalPath %q", v.NatTraversalPath)
}
if v.Reason != nil && !enumOf(*v.Reason, senderQualityDegradedReasons...) {
return fmt.Errorf("unknown sender quality reason %q", *v.Reason)
}
for _, bound := range []struct {
value *Num
minimum, maximum float64
}{
{v.FramesPerSecond, 0, MaxSafeInteger}, {v.BitrateKbps, 0, MaxSafeInteger},
{v.CaptureFramesPerSecond.Value, 0, MaxSafeInteger},
{v.MediaSourceFramesPerSecond.Value, 0, MaxSafeInteger},
{v.AvailableOutgoingKbps.Value, 0, MaxSafeInteger},
{v.RttMs.Value, 0, MaxSafeInteger}, {v.PacketLossPercent.Value, 0, 100},
} {
if bound.value != nil && !inRangeNum(*bound.value, bound.minimum, bound.maximum) {
return errors.New("sender quality diagnostic number is out of range")
}
}
for _, bound := range []struct {
value *Int
maximum int64
}{
{v.Width.Value, MaxSafeInteger}, {v.Height.Value, MaxSafeInteger},
{v.VideoEncodingCount.Value, MaxSafeInteger},
{v.ActiveVideoEncodingCount.Value, MaxSafeInteger},
} {
if bound.value != nil && !inRangeInt(*bound.value, 0, bound.maximum) {
return errors.New("sender quality diagnostic integer is out of range")
}
}
return nil
}