fix(gateway): enforce audited production traversal

This commit is contained in:
sechmachine
2026-07-30 04:48:02 +07:00
parent d3852d15f3
commit 70667d5aee
17 changed files with 1368 additions and 317 deletions
+61 -13
View File
@@ -198,12 +198,16 @@ func pinnedApolloTLSConfig(work protocol.ProviderSessionWork) (*tls.Config, erro
}, nil }, nil
} }
func (b *NativeApolloBackend) Setup(ctx context.Context, request LaunchRequest) ([]byte, error) { func (b *NativeApolloBackend) Setup(ctx context.Context, request LaunchRequest, management []byte) ([]byte, error) {
work := request.ProviderWork work := request.ProviderWork
if err := work.Validate(); err != nil || validateApolloStreamPolicy(work.StreamPolicy) != nil || if err := work.Validate(); err != nil || validateApolloStreamPolicy(work.StreamPolicy) != nil ||
request.SessionID == "" || request.SessionID != work.SessionID || work.ProviderProfile != ProviderProfileApollo { request.SessionID == "" || request.SessionID != work.SessionID || work.ProviderProfile != ProviderProfileApollo {
return nil, ErrProviderMalformed return nil, ErrProviderMalformed
} }
info, err := ParseManagementXML(management)
if err != nil || validateApolloProviderStreamPolicy(info, work.StreamPolicy) != nil {
return nil, ErrProviderMalformed
}
client, err := newPinnedApolloHTTPClient(work) client, err := newPinnedApolloHTTPClient(work)
if err != nil { if err != nil {
return nil, err return nil, err
@@ -281,10 +285,11 @@ type nativeApolloSession struct {
audioPing []byte audioPing []byte
videoPing []byte videoPing []byte
sessionID string sessionID string
video chan []byte video chan ProviderMedia
audio chan []byte audio chan ProviderMedia
events chan ProviderEvent events chan ProviderEvent
mu sync.Mutex mu sync.Mutex
mediaMu sync.Mutex
controlMu sync.Mutex controlMu sync.Mutex
state protocol.ProviderState state protocol.ProviderState
pressed map[string]InputEvent pressed map[string]InputEvent
@@ -299,10 +304,15 @@ type nativeApolloSession struct {
allowApplicationTermination bool allowApplicationTermination bool
terminationErr error terminationErr error
mediaDrops atomic.Uint64 mediaDrops atomic.Uint64
mediaQuiesced atomic.Bool
mediaIngress atomic.Uint64
mediaRecovered atomic.Uint64
mediaEnqueued atomic.Uint64
mediaQueueMaximum atomic.Uint64
} }
func newNativeApolloSession(sessionID string) *nativeApolloSession { func newNativeApolloSession(sessionID string) *nativeApolloSession {
return &nativeApolloSession{sessionID: sessionID, video: make(chan []byte, 16), audio: make(chan []byte, 16), events: make(chan ProviderEvent, 16), state: protocol.ProviderState{Version: "1", SessionID: sessionID, State: ProviderStateStarting, Channels: []string{"video", "audio", "input", "feedback"}}, pressed: make(map[string]InputEvent), done: make(chan struct{}), readDone: make(chan struct{})} return &nativeApolloSession{sessionID: sessionID, video: make(chan ProviderMedia, 16), audio: make(chan ProviderMedia, 16), events: make(chan ProviderEvent, 16), state: protocol.ProviderState{Version: "1", SessionID: sessionID, State: ProviderStateStarting, Channels: []string{"video", "audio", "input", "feedback"}}, pressed: make(map[string]InputEvent), done: make(chan struct{}), readDone: make(chan struct{})}
} }
func newNativeApolloProviderSession(ctx context.Context, setup *apolloRTSPSetup) (*nativeApolloSession, error) { func newNativeApolloProviderSession(ctx context.Context, setup *apolloRTSPSetup) (*nativeApolloSession, error) {
@@ -405,8 +415,8 @@ func (s *nativeApolloSession) Ready(context.Context) error {
return nil return nil
} }
func (s *nativeApolloSession) Video() <-chan []byte { return s.video } func (s *nativeApolloSession) Video() <-chan ProviderMedia { return s.video }
func (s *nativeApolloSession) Audio() <-chan []byte { return s.audio } func (s *nativeApolloSession) Audio() <-chan ProviderMedia { return s.audio }
func (s *nativeApolloSession) Events() <-chan ProviderEvent { return s.events } func (s *nativeApolloSession) Events() <-chan ProviderEvent { return s.events }
func (s *nativeApolloSession) Input(ctx context.Context, event InputEvent) error { func (s *nativeApolloSession) Input(ctx context.Context, event InputEvent) error {
@@ -646,6 +656,7 @@ func (s *nativeApolloSession) handleApolloControlPayload(_ uint8, _ bool, payloa
s.handleApolloDisconnect(ErrProviderMalformed) s.handleApolloDisconnect(ErrProviderMalformed)
return return
} }
s.quiesceMedia()
s.mu.Lock() s.mu.Lock()
s.state.State = ProviderStateTerminated s.state.State = ProviderStateTerminated
s.mu.Unlock() s.mu.Unlock()
@@ -686,6 +697,7 @@ func (s *nativeApolloSession) handleApolloDisconnect(err error) {
if err == nil { if err == nil {
return return
} }
s.quiesceMedia()
s.disconnectOnce.Do(func() { s.disconnectOnce.Do(func() {
s.mu.Lock() s.mu.Lock()
if s.state.State == ProviderStateTerminated { if s.state.State == ProviderStateTerminated {
@@ -701,13 +713,45 @@ func (s *nativeApolloSession) handleApolloDisconnect(err error) {
}) })
} }
func (s *nativeApolloSession) quiesceMedia() {
if !s.mediaQuiesced.CompareAndSwap(false, true) {
return
}
if s.audioConn != nil {
_ = s.audioConn.Close()
}
if s.videoConn != nil {
_ = s.videoConn.Close()
}
}
func (s *nativeApolloSession) closeMediaChannels() { func (s *nativeApolloSession) closeMediaChannels() {
s.channelsOnce.Do(func() { s.channelsOnce.Do(func() {
s.mediaMu.Lock()
defer s.mediaMu.Unlock()
close(s.video) close(s.video)
close(s.audio) close(s.audio)
}) })
} }
func (s *nativeApolloSession) enqueueMedia(output chan ProviderMedia, payload []byte, receivedAt time.Time) bool {
s.mediaMu.Lock()
defer s.mediaMu.Unlock()
if len(payload) == 0 || s.mediaQuiesced.Load() {
return false
}
s.mediaRecovered.Add(1)
media := ProviderMedia{Payload: payload, ReceivedAt: receivedAt, EnqueuedAt: time.Now()}
if pushLatest(output, media) {
s.mediaDrops.Add(1)
}
s.mediaEnqueued.Add(1)
depth := uint64(len(output))
for maximum := s.mediaQueueMaximum.Load(); depth > maximum && !s.mediaQueueMaximum.CompareAndSwap(maximum, depth); maximum = s.mediaQueueMaximum.Load() {
}
return true
}
func (s *nativeApolloSession) readUDPMedia() { func (s *nativeApolloSession) readUDPMedia() {
if s.media == nil { if s.media == nil {
close(s.readDone) close(s.readDone)
@@ -716,14 +760,18 @@ func (s *nativeApolloSession) readUDPMedia() {
} }
var readers sync.WaitGroup var readers sync.WaitGroup
readers.Add(2) readers.Add(2)
read := func(conn *net.UDPConn, output chan []byte, video bool) { read := func(conn *net.UDPConn, output chan ProviderMedia, video bool) {
defer readers.Done() defer readers.Done()
buffer := make([]byte, apolloMediaMaximumPacket+1) buffer := make([]byte, apolloMediaMaximumPacket+1)
for { for {
if s.mediaQuiesced.Load() {
return
}
if err := conn.SetReadDeadline(time.Now().Add(250 * time.Millisecond)); err != nil { if err := conn.SetReadDeadline(time.Now().Add(250 * time.Millisecond)); err != nil {
return return
} }
count, err := conn.Read(buffer) count, err := conn.Read(buffer)
receivedAt := time.Now()
if err != nil { if err != nil {
if networkErr, ok := err.(net.Error); ok && networkErr.Timeout() { if networkErr, ok := err.(net.Error); ok && networkErr.Timeout() {
select { select {
@@ -738,6 +786,10 @@ func (s *nativeApolloSession) readUDPMedia() {
if count > apolloMediaMaximumPacket { if count > apolloMediaMaximumPacket {
continue continue
} }
if s.mediaQuiesced.Load() {
return
}
s.mediaIngress.Add(1)
var payloads [][]byte var payloads [][]byte
if video { if video {
shard, openErr := s.media.OpenVideo(buffer[:count]) shard, openErr := s.media.OpenVideo(buffer[:count])
@@ -764,11 +816,7 @@ func (s *nativeApolloSession) readUDPMedia() {
continue continue
} }
for _, payload := range payloads { for _, payload := range payloads {
if len(payload) != 0 { s.enqueueMedia(output, payload, receivedAt)
if pushLatest(output, payload) {
s.mediaDrops.Add(1)
}
}
} }
} }
} }
@@ -781,7 +829,7 @@ func (s *nativeApolloSession) readUDPMedia() {
}() }()
} }
func pushLatest(channel chan []byte, payload []byte) bool { func pushLatest[T any](channel chan T, payload T) bool {
select { select {
case channel <- payload: case channel <- payload:
return false return false
+88 -10
View File
@@ -84,12 +84,16 @@ func TestNativeApolloSetupRejectsUnsupportedStreamPolicyBeforeProviderReadiness(
for name, policy := range map[string]protocol.ProviderStreamPolicy{ for name, policy := range map[string]protocol.ProviderStreamPolicy{
"audio-disabled": {ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60, Codec: "H264", BitrateKbps: 8000, AudioEnabled: false}, "audio-disabled": {ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60, Codec: "H264", BitrateKbps: 8000, AudioEnabled: false},
"av1": {ResolutionWidth: 3840, ResolutionHeight: 2160, Fps: 60, Codec: "AV1", BitrateKbps: 50000, AudioEnabled: true}, "av1": {ResolutionWidth: 3840, ResolutionHeight: 2160, Fps: 60, Codec: "AV1", BitrateKbps: 50000, AudioEnabled: true},
"h264-resolution": {ResolutionWidth: 4097, ResolutionHeight: 2160, Fps: 60, Codec: "H264", BitrateKbps: 50000, AudioEnabled: true},
"hevc-resolution": {ResolutionWidth: 8193, ResolutionHeight: 4320, Fps: 60, Codec: "HEVC", BitrateKbps: 80000, AudioEnabled: true},
"fps": {ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 241, Codec: "H264", BitrateKbps: 8000, AudioEnabled: true},
"bitrate-cap": {ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60, Codec: "H264", BitrateKbps: 125001, AudioEnabled: true},
} { } {
t.Run(name, func(t *testing.T) { t.Run(name, func(t *testing.T) {
work.StreamPolicy = policy work.StreamPolicy = policy
_, err := NewNativeApolloBackend().Setup(context.Background(), LaunchRequest{ _, err := NewNativeApolloBackend().Setup(context.Background(), LaunchRequest{
SessionID: "session-1", ProviderProfile: ProviderProfileApollo, ProviderWork: work, SessionID: "session-1", ProviderProfile: ProviderProfileApollo, ProviderWork: work,
}) }, nil)
if !errors.Is(err, ErrProviderMalformed) { if !errors.Is(err, ErrProviderMalformed) {
t.Fatalf("Setup() error = %v, want ErrProviderMalformed before provider readiness", err) t.Fatalf("Setup() error = %v, want ErrProviderMalformed before provider readiness", err)
} }
@@ -97,6 +101,73 @@ func TestNativeApolloSetupRejectsUnsupportedStreamPolicyBeforeProviderReadiness(
} }
} }
func TestNativeApolloRejectsProviderCapabilityMismatchBeforeInventoryOrLaunch(t *testing.T) {
serverTLS, clientTLS := testTLS(t)
var paths []string
management := httptest.NewUnstartedServer(http.HandlerFunc(func(response http.ResponseWriter, request *http.Request) {
paths = append(paths, request.URL.Path)
switch request.URL.Path {
case "/serverinfo":
_, _ = response.Write([]byte("<root><uniqueid>apollo-server</uniqueid><ServerCodecModeSupport>1</ServerCodecModeSupport><MaxLumaPixelsHEVC>0</MaxLumaPixelsHEVC></root>"))
case "/applist":
_, _ = response.Write([]byte("<root><App><ID>42</ID></App></root>"))
default:
http.Error(response, "unexpected provider request", http.StatusBadRequest)
}
}))
management.TLS = serverTLS
management.StartTLS()
defer management.Close()
host, portText, err := net.SplitHostPort(management.Listener.Addr().String())
if err != nil {
t.Fatal(err)
}
port, err := strconv.ParseInt(portText, 10, 64)
if err != nil {
t.Fatal(err)
}
pinned := sha256.Sum256(serverTLS.Certificates[0].Certificate[0])
work := protocol.ProviderSessionWork{
Version: "1", SessionID: "session-source-policy", GatewayID: "gateway-1",
ExpiresAt: "2099-01-01T00:00:00Z", ProviderProfile: ProviderProfileApollo,
ProviderIdentity: "apollo-server#sha256:" + hex.EncodeToString(pinned[:]), PolicyVersionID: "policy-1",
ApplicationID: "42", ClientID: "paired-client",
StreamPolicy: protocol.ProviderStreamPolicy{
ResolutionWidth: 2560, ResolutionHeight: 1440, Fps: 120,
Codec: "HEVC", BitrateKbps: 40000, AudioEnabled: true,
},
ManagementHost: host, ManagementPort: port, StreamHost: host, StreamPort: 47984,
ClientCertificatePem: certificatePEM(t, clientTLS.Certificates[0]),
ClientPrivateKeyPem: privateKeyPEM(t, clientTLS.Certificates[0]),
ServerCertificatePem: certificatePEM(t, tls.Certificate{Certificate: [][]byte{serverTLS.Certificates[0].Certificate[1]}}),
ClipboardPolicy: protocol.ClipboardPolicy{MaxTextBytes: 65536, MaxUpdatesPerMinute: 30},
}
adapter := NewApolloAdapter(NewNativeApolloBackend(), ProviderIdentity{UniqueID: "apollo-server", Fingerprint: "sha256:" + hex.EncodeToString(pinned[:])})
if _, err := adapter.Start(context.Background(), LaunchRequest{
SessionID: work.SessionID, ProviderProfile: ProviderProfileApollo,
ProviderIdentity: work.ProviderIdentity, ProviderWork: work,
}); err == nil {
t.Fatal("Start() accepted a provider/source policy mismatch")
}
if got := strings.Join(paths, ","); got != "/serverinfo" {
t.Fatalf("provider requests before capability rejection = %s", got)
}
}
func TestApolloProviderCapabilityRejectsHEVCLumaDowngrade(t *testing.T) {
info := ManagementInfo{
ServerCodecModeSupport: 0x101, HasServerCodecModeSupport: true,
MaxLumaPixelsHEVC: 1920 * 1080, HasMaxLumaPixelsHEVC: true,
}
policy := protocol.ProviderStreamPolicy{
ResolutionWidth: 3840, ResolutionHeight: 2160, Fps: 60,
Codec: "HEVC", BitrateKbps: 80000, AudioEnabled: true,
}
if err := validateApolloProviderStreamPolicy(info, policy); !errors.Is(err, ErrProviderMalformed) {
t.Fatalf("provider HEVC luma downgrade error = %v", err)
}
}
func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) { func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) {
serverTLS, clientTLS := testTLS(t) serverTLS, clientTLS := testTLS(t)
streamListener, err := net.Listen("tcp", "127.0.0.1:0") streamListener, err := net.Listen("tcp", "127.0.0.1:0")
@@ -213,7 +284,7 @@ func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) {
} }
switch request.URL.Path { switch request.URL.Path {
case "/serverinfo": case "/serverinfo":
_, _ = response.Write([]byte("<root><uniqueid>apollo-server</uniqueid></root>")) _, _ = response.Write([]byte("<root><uniqueid>apollo-server</uniqueid><ServerCodecModeSupport>257</ServerCodecModeSupport><MaxLumaPixelsHEVC>1869449984</MaxLumaPixelsHEVC></root>"))
case "/applist": case "/applist":
if request.URL.Query().Get("uniqueid") != "paired-client" { if request.URL.Query().Get("uniqueid") != "paired-client" {
http.Error(response, "wrong client", http.StatusBadRequest) http.Error(response, "wrong client", http.StatusBadRequest)
@@ -291,7 +362,7 @@ func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) {
ProviderApplicationTerminationAllowed: true, ProviderApplicationTerminationAllowed: true,
} }
backend := NewNativeApolloBackend() backend := NewNativeApolloBackend()
response, err := backend.Setup(context.Background(), LaunchRequest{SessionID: "session-1", ProviderProfile: ProviderProfileApollo, ProviderWork: work}) response, err := backend.Setup(context.Background(), LaunchRequest{SessionID: "session-1", ProviderProfile: ProviderProfileApollo, ProviderWork: work}, []byte("<root><uniqueid>apollo-server</uniqueid><ServerCodecModeSupport>257</ServerCodecModeSupport><MaxLumaPixelsHEVC>1869449984</MaxLumaPixelsHEVC></root>"))
if err != nil { if err != nil {
t.Fatalf("Setup() error = %v", err) t.Fatalf("Setup() error = %v", err)
} }
@@ -474,7 +545,8 @@ func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) {
t.Fatal("encrypted host termination was not forwarded") t.Fatal("encrypted host termination was not forwarded")
} }
select { select {
case payload := <-session.Video(): case media := <-session.Video():
payload := media.Payload
if len(payload) != 1001 || payload[0] != 'A' || payload[1000] != 'B' { if len(payload) != 1001 || payload[0] != 'A' || payload[1000] != 'B' {
t.Fatalf("source-shaped video relay = %x", payload) t.Fatalf("source-shaped video relay = %x", payload)
} }
@@ -482,7 +554,8 @@ func TestNativeApolloSetupRequiresModernEncryptedRTSPOrder(t *testing.T) {
t.Fatal("source-shaped video was not relayed") t.Fatal("source-shaped video was not relayed")
} }
select { select {
case payload := <-session.Audio(): case media := <-session.Audio():
payload := media.Payload
if string(payload) != "A" { if string(payload) != "A" {
t.Fatalf("source-shaped audio relay = %x", payload) t.Fatalf("source-shaped audio relay = %x", payload)
} }
@@ -608,7 +681,8 @@ func TestNativeApolloSessionRelaysOnlyAuthenticatedEncodedUDPMedia(t *testing.T)
} }
select { select {
case payload := <-session.Video(): case media := <-session.Video():
payload := media.Payload
if string(payload) != string([]byte{0x01, 0x02, 0x03}) { if string(payload) != string([]byte{0x01, 0x02, 0x03}) {
t.Fatalf("video relay = %x, want encoded payload", payload) t.Fatalf("video relay = %x, want encoded payload", payload)
} }
@@ -617,7 +691,8 @@ func TestNativeApolloSessionRelaysOnlyAuthenticatedEncodedUDPMedia(t *testing.T)
} }
for _, want := range wantAudio { for _, want := range wantAudio {
select { select {
case payload := <-session.Audio(): case media := <-session.Audio():
payload := media.Payload
if string(payload) != string(want) { if string(payload) != string(want) {
t.Fatalf("audio relay = %x, want %x", payload, want) t.Fatalf("audio relay = %x, want %x", payload, want)
} }
@@ -632,7 +707,8 @@ func TestNativeApolloSessionRelaysOnlyAuthenticatedEncodedUDPMedia(t *testing.T)
} }
} }
select { select {
case payload := <-session.Video(): case media := <-session.Video():
payload := media.Payload
if len(payload) != 1001 || payload[0] != 'A' || payload[999] != 'A' || payload[1000] != 'B' { if len(payload) != 1001 || payload[0] != 'A' || payload[999] != 'A' || payload[1000] != 'B' {
t.Fatalf("FEC video relay = %x", payload) t.Fatalf("FEC video relay = %x", payload)
} }
@@ -646,7 +722,8 @@ func TestNativeApolloSessionRelaysOnlyAuthenticatedEncodedUDPMedia(t *testing.T)
} }
for _, want := range [][]byte{{'A'}, {'B'}, {'C'}, {'D'}} { for _, want := range [][]byte{{'A'}, {'B'}, {'C'}, {'D'}} {
select { select {
case payload := <-session.Audio(): case media := <-session.Audio():
payload := media.Payload
if string(payload) != string(want) { if string(payload) != string(want) {
t.Fatalf("FEC audio relay = %x, want %x", payload, want) t.Fatalf("FEC audio relay = %x, want %x", payload, want)
} }
@@ -670,7 +747,8 @@ func TestNativeApolloSessionRelaysOnlyAuthenticatedEncodedUDPMedia(t *testing.T)
} }
for _, want := range [][]byte{{0xa0}, {0xa1}, {0xa2}, {0xa3}} { for _, want := range [][]byte{{0xa0}, {0xa1}, {0xa2}, {0xa3}} {
select { select {
case payload := <-session.Audio(): case media := <-session.Audio():
payload := media.Payload
if string(payload) != string(want) { if string(payload) != string(want) {
t.Fatalf("post-loss audio relay = %x, want %x", payload, want) t.Fatalf("post-loss audio relay = %x, want %x", payload, want)
} }
+26 -1
View File
@@ -515,7 +515,32 @@ func apolloAnnounceProfile(policy protocol.ProviderStreamPolicy) ([]byte, error)
} }
func validateApolloStreamPolicy(policy protocol.ProviderStreamPolicy) error { func validateApolloStreamPolicy(policy protocol.ProviderStreamPolicy) error {
if err := policy.Validate(); err != nil || !policy.AudioEnabled || (policy.Codec != "H264" && policy.Codec != "HEVC") { if err := policy.Validate(); err != nil || !policy.AudioEnabled || policy.BitrateKbps > 125000 ||
(policy.Codec != "H264" && policy.Codec != "HEVC") {
return ErrProviderMalformed
}
if (policy.Codec == "H264" && (policy.ResolutionWidth > 4096 || policy.ResolutionHeight > 4096)) ||
(policy.Codec == "HEVC" && (policy.ResolutionWidth > 8192 || policy.ResolutionHeight > 8192)) {
return ErrProviderMalformed
}
return nil
}
func validateApolloProviderStreamPolicy(info ManagementInfo, policy protocol.ProviderStreamPolicy) error {
if validateApolloStreamPolicy(policy) != nil || !info.HasServerCodecModeSupport || !info.HasMaxLumaPixelsHEVC {
return ErrProviderMalformed
}
switch policy.Codec {
case "H264":
if info.ServerCodecModeSupport&0x1 == 0 {
return ErrProviderMalformed
}
case "HEVC":
luma := uint64(policy.ResolutionWidth) * uint64(policy.ResolutionHeight)
if info.ServerCodecModeSupport&0x100 == 0 || info.MaxLumaPixelsHEVC == 0 || luma > info.MaxLumaPixelsHEVC {
return ErrProviderMalformed
}
default:
return ErrProviderMalformed return ErrProviderMalformed
} }
return nil return nil
+8 -20
View File
@@ -8,8 +8,6 @@ import (
var ErrNoCapabilityOverlap = errors.New("no capability overlap") var ErrNoCapabilityOverlap = errors.New("no capability overlap")
const defaultClientDecode = "h264-hevc-opus"
func DefaultCapabilities() protocol.CapabilityProfile { func DefaultCapabilities() protocol.CapabilityProfile {
return protocol.CapabilityProfile{ return protocol.CapabilityProfile{
Transport: "quic-tls13", Transport: "quic-tls13",
@@ -17,29 +15,19 @@ func DefaultCapabilities() protocol.CapabilityProfile {
Media: "encoded", Media: "encoded",
Audio: "encoded", Audio: "encoded",
SourceRateControl: "server", SourceRateControl: "server",
ClientDecode: defaultClientDecode, ClientDecode: []string{"hevc-opus", "h264-opus"},
} }
} }
func capabilityProfileUnset(profile protocol.CapabilityProfile) bool {
return profile.Transport == "" && profile.Framing == "" && profile.Media == "" &&
profile.Audio == "" && profile.SourceRateControl == "" && len(profile.ClientDecode) == 0
}
func IntersectCapabilities(profiles ...protocol.CapabilityProfile) (protocol.CapabilityProfile, error) { func IntersectCapabilities(profiles ...protocol.CapabilityProfile) (protocol.CapabilityProfile, error) {
if len(profiles) == 0 { selected, err := protocol.IntersectCapabilityProfiles(profiles...)
if err != nil {
return protocol.CapabilityProfile{}, ErrNoCapabilityOverlap return protocol.CapabilityProfile{}, ErrNoCapabilityOverlap
} }
for _, profile := range profiles {
if err := profile.Validate(); err != nil {
return protocol.CapabilityProfile{}, ErrNoCapabilityOverlap
}
}
selected := profiles[0]
for _, profile := range profiles[1:] {
if selected.Transport != profile.Transport ||
selected.Framing != profile.Framing ||
selected.Media != profile.Media ||
selected.Audio != profile.Audio ||
selected.SourceRateControl != profile.SourceRateControl ||
selected.ClientDecode != profile.ClientDecode {
return protocol.CapabilityProfile{}, ErrNoCapabilityOverlap
}
}
return selected, nil return selected, nil
} }
+11
View File
@@ -18,6 +18,7 @@ const (
gatewayFeedbackTerminated = 0x10 gatewayFeedbackTerminated = 0x10
gatewayFeedbackRumble = 0x11 gatewayFeedbackRumble = 0x11
gatewayFeedbackHDR = 0x12 gatewayFeedbackHDR = 0x12
gatewayFeedbackDisconnected = 0x13
) )
type gatewayFeedbackMessage struct { type gatewayFeedbackMessage struct {
@@ -43,6 +44,11 @@ func EncodeProviderEvent(event ProviderEvent) ([]byte, error) {
return nil, ErrProviderMalformed return nil, ErrProviderMalformed
} }
return encodeGatewayFeedback(gatewayFeedbackGateway, gatewayFeedbackHDR, event.Payload) return encodeGatewayFeedback(gatewayFeedbackGateway, gatewayFeedbackHDR, event.Payload)
case ProviderEventDisconnected:
if len(event.Payload) != 0 {
return nil, ErrProviderMalformed
}
return encodeGatewayFeedback(gatewayFeedbackGateway, gatewayFeedbackDisconnected, nil)
default: default:
return nil, ErrProviderMalformed return nil, ErrProviderMalformed
} }
@@ -120,6 +126,11 @@ func DecodeProviderEvent(data []byte) (ProviderEvent, error) {
return ProviderEvent{}, ErrProviderMalformed return ProviderEvent{}, ErrProviderMalformed
} }
return ProviderEvent{Kind: ProviderEventHDR, Payload: message.payload}, nil return ProviderEvent{Kind: ProviderEventHDR, Payload: message.payload}, nil
case gatewayFeedbackDisconnected:
if len(message.payload) != 0 {
return ProviderEvent{}, ErrProviderMalformed
}
return ProviderEvent{Kind: ProviderEventDisconnected}, nil
default: default:
return ProviderEvent{}, ErrProviderMalformed return ProviderEvent{}, ErrProviderMalformed
} }
+267 -22
View File
@@ -14,6 +14,7 @@ import (
"math/big" "math/big"
"net" "net"
"os" "os"
"reflect"
"strings" "strings"
"sync" "sync"
"sync/atomic" "sync/atomic"
@@ -97,6 +98,13 @@ func TestClientFeedbackUsesFixedProtocolVGFVector(t *testing.T) {
if _, err := DecodeClientFeedback([]byte{'F', 'B', 'R', 'K', 0}); !errors.Is(err, ErrProviderMalformed) { if _, err := DecodeClientFeedback([]byte{'F', 'B', 'R', 'K', 0}); !errors.Is(err, ErrProviderMalformed) {
t.Fatalf("legacy feedback accepted: %v", err) t.Fatalf("legacy feedback accepted: %v", err)
} }
disconnected, err := EncodeProviderEvent(ProviderEvent{Kind: ProviderEventDisconnected})
if err != nil || hex.EncodeToString(disconnected) != "5647463101130000" {
t.Fatalf("disconnected event vector = %x, %v", disconnected, err)
}
if event, err := DecodeProviderEvent(disconnected); err != nil || event.Kind != ProviderEventDisconnected {
t.Fatalf("decoded disconnected event = %#v, %v", event, err)
}
} }
func TestCapabilityIntersectionAndBoundedQueue(t *testing.T) { func TestCapabilityIntersectionAndBoundedQueue(t *testing.T) {
@@ -124,6 +132,24 @@ func TestCapabilityIntersectionAndBoundedQueue(t *testing.T) {
} }
} }
func TestNewServerRejectsPartiallyConfiguredCapabilities(t *testing.T) {
serverTLS, _ := testTLS(t)
fake := NewFakeApollo(FakeApolloConfig{Now: time.Now()})
server, err := NewServer(ServerConfig{
TLSConfig: serverTLS, GatewayID: "gateway-1",
Capabilities: protocol.CapabilityProfile{SourceRateControl: "server"},
ProviderCapabilities: DefaultCapabilities(),
Admission: &oneTimeAdmission{},
Provider: fake,
})
if server != nil {
_ = server.Close()
}
if err == nil {
t.Fatal("partial capability configuration was silently replaced with defaults")
}
}
func TestSyntheticImpairmentPacingAndResourceBounds(t *testing.T) { func TestSyntheticImpairmentPacingAndResourceBounds(t *testing.T) {
payload := make([]byte, 1179*16+1) payload := make([]byte, 1179*16+1)
if _, err := FragmentPayload(ChannelVideo, 1, 0, payload); !errors.Is(err, ErrFrameFragmentedLimit) { if _, err := FragmentPayload(ChannelVideo, 1, 0, payload); !errors.Is(err, ErrFrameFragmentedLimit) {
@@ -187,10 +213,10 @@ func TestApolloFixturesAndLifecycle(t *testing.T) {
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
if got := <-session.Video(); string(got) != string(video) { if got := <-session.Video(); string(got.Payload) != string(video) {
t.Fatalf("video changed: %x", got) t.Fatalf("video changed: %x", got)
} }
if got := <-session.Audio(); string(got) != string(audio) { if got := <-session.Audio(); string(got.Payload) != string(audio) {
t.Fatalf("audio changed: %x", got) t.Fatalf("audio changed: %x", got)
} }
if err := session.Input(context.Background(), InputEvent{Sequence: 1, Device: "keyboard", Code: 7, Pressed: true}); err != nil { if err := session.Input(context.Background(), InputEvent{Sequence: 1, Device: "keyboard", Code: 7, Pressed: true}); err != nil {
@@ -321,11 +347,96 @@ func TestAdmissionQUICMTLSRelayAndCleanup(t *testing.T) {
} }
} }
func TestGatewayTelemetrySeparatesQueueProcessingAndPacing(t *testing.T) {
serverTLS, clientTLS := testTLS(t)
session := &fakeSession{
video: make(chan ProviderMedia, 1),
audio: make(chan ProviderMedia),
events: make(chan ProviderEvent, 1),
clipboardWrites: make(chan string, 1),
state: protocol.ProviderState{
Version: "1", SessionID: "session-timing", State: ProviderStateStarting,
Channels: []string{"video", "audio", "input", "feedback"},
},
pressed: make(map[string]struct{}),
}
provider := providerStartFunc(func(context.Context, LaunchRequest) (ProviderSession, error) {
enqueuedAt := time.Now()
session.video <- ProviderMedia{Payload: bytesRepeat(0x5a, 2000), ReceivedAt: enqueuedAt, EnqueuedAt: enqueuedAt}
time.Sleep(60 * time.Millisecond)
session.mu.Lock()
session.state.State = ProviderStateReady
session.mu.Unlock()
return session, nil
})
authority := protocol.SessionAuthority{
Version: "1", SessionID: "session-timing", GatewayID: "gateway-1", Audience: "versevdi-gateway",
ExpiresAt: time.Now().Add(5 * time.Second).UTC().Format(time.RFC3339Nano),
Capabilities: DefaultCapabilities(), ProviderProfile: ProviderProfileApollo,
ProviderIdentity: "apollo-fixture-1#sha256:fixture-apollo-1",
}
admission := &oneTimeAdmission{authority: authority, released: make(chan struct{}), disableClipboard: true}
server, err := NewServer(ServerConfig{
ListenAddress: "127.0.0.1:0", TLSConfig: serverTLS, GatewayID: authority.GatewayID,
Capabilities: DefaultCapabilities(), ProviderCapabilities: DefaultCapabilities(),
Admission: admission, Provider: provider, PacerKbps: 24,
})
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
serveDone := make(chan error, 1)
go func() { serveDone <- server.Serve(ctx) }()
request := protocol.TunnelAdmissionRequest{
Version: "1", SessionID: authority.SessionID, GatewayID: authority.GatewayID, Audience: authority.Audience,
Grant: strings.Repeat("g", 64), ClientNonce: "nonce-0000000001", DeviceSignature: strings.Repeat("s", 86),
Capabilities: DefaultCapabilities(),
}
client, err := Dial(context.Background(), server.Addr().String(), clientTLS, request)
if err != nil {
t.Fatal(err)
}
receiveCtx, receiveCancel := context.WithTimeout(context.Background(), 2*time.Second)
for index := byte(0); index < 2; index++ {
frame, err := client.ReceiveFrame(receiveCtx)
if err != nil {
t.Fatal(err)
}
if frame.FragmentIndex != index || frame.FragmentCount != 2 {
t.Fatalf("timing frame = %#v", frame)
}
}
receiveCancel()
metrics := server.Metrics()
if metrics.ProcessingSamples != 1 {
t.Fatalf("timing samples = %d, want one provider unit", metrics.ProcessingSamples)
}
if metrics.MediaPackets != 2 {
t.Fatalf("media packets = %d, want two fragments", metrics.MediaPackets)
}
queue, processing, pacing := time.Duration(metrics.QueueDelayNanos), time.Duration(metrics.ProcessingDelayNanos), time.Duration(metrics.PacingDelayNanos)
if queue < 40*time.Millisecond || queue > 150*time.Millisecond {
t.Fatalf("queue residence = %s, want the controlled 60ms provider queue wait", queue)
}
if processing >= 100*time.Millisecond {
t.Fatalf("processing = %s, pacing leaked into gateway processing", processing)
}
if pacing < 500*time.Millisecond {
t.Fatalf("pacing = %s, want the controlled scheduler wait", pacing)
}
_ = client.Close()
cancel()
_ = server.Close()
if err := <-serveDone; err != nil {
t.Fatal(err)
}
}
func TestGatewayRejectsProviderWorkOutsideNegotiatedDecodeProfile(t *testing.T) { func TestGatewayRejectsProviderWorkOutsideNegotiatedDecodeProfile(t *testing.T) {
serverTLS, clientTLS := testTLS(t) serverTLS, clientTLS := testTLS(t)
fake := NewFakeApollo(FakeApolloConfig{Now: time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)}) fake := NewFakeApollo(FakeApolloConfig{Now: time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)})
capabilities := DefaultCapabilities() capabilities := DefaultCapabilities()
capabilities.ClientDecode = "h264-opus" capabilities.ClientDecode = []string{"h264-opus"}
authority := protocol.SessionAuthority{ authority := protocol.SessionAuthority{
Version: "1", SessionID: "session-policy", GatewayID: "gateway-1", Audience: "versevdi-gateway", Version: "1", SessionID: "session-policy", GatewayID: "gateway-1", Audience: "versevdi-gateway",
ExpiresAt: time.Now().Add(5 * time.Second).UTC().Format(time.RFC3339Nano), ExpiresAt: time.Now().Add(5 * time.Second).UTC().Format(time.RFC3339Nano),
@@ -371,6 +482,75 @@ func TestGatewayRejectsProviderWorkOutsideNegotiatedDecodeProfile(t *testing.T)
} }
} }
func TestGatewayNegotiatesRegisteredProfilesWithIndependentClient(t *testing.T) {
for _, test := range []struct {
name string
clientProfiles []string
selected string
codec string
}{
{name: "h264-only", clientProfiles: []string{"h264-opus"}, selected: "h264-opus", codec: "H264"},
{name: "hevc-only", clientProfiles: []string{"hevc-opus"}, selected: "hevc-opus", codec: "HEVC"},
{name: "policy-selects-hevc", clientProfiles: []string{"h264-opus", "hevc-opus"}, selected: "hevc-opus", codec: "HEVC"},
} {
t.Run(test.name, func(t *testing.T) {
serverTLS, clientTLS := testTLS(t)
fake := NewFakeApollo(FakeApolloConfig{Now: time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)})
clientCapabilities := DefaultCapabilities()
clientCapabilities.ClientDecode = test.clientProfiles
authority := protocol.SessionAuthority{
Version: "1", SessionID: "session-profile-" + test.name, GatewayID: "gateway-1", Audience: "versevdi-gateway",
ExpiresAt: time.Now().Add(5 * time.Second).UTC().Format(time.RFC3339Nano),
Capabilities: clientCapabilities, ProviderProfile: ProviderProfileApollo, ProviderIdentity: fake.config.Identity.Key(),
}
admission := &oneTimeAdmission{
authority: authority, released: make(chan struct{}), disableClipboard: true,
streamPolicy: protocol.ProviderStreamPolicy{
ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60,
Codec: test.codec, BitrateKbps: 8000, AudioEnabled: true,
},
}
started := make(chan LaunchRequest, 1)
provider := providerStartFunc(func(ctx context.Context, request LaunchRequest) (ProviderSession, error) {
started <- request
return fake.Start(ctx, request)
})
server, err := NewServer(ServerConfig{
ListenAddress: "127.0.0.1:0", TLSConfig: serverTLS, GatewayID: authority.GatewayID,
Capabilities: DefaultCapabilities(), ProviderCapabilities: DefaultCapabilities(),
Admission: admission, Provider: provider,
})
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
serveDone := make(chan error, 1)
go func() { serveDone <- server.Serve(ctx) }()
request := protocol.TunnelAdmissionRequest{
Version: "1", SessionID: authority.SessionID, GatewayID: authority.GatewayID, Audience: authority.Audience,
Grant: strings.Repeat("g", 64), ClientNonce: "nonce-0000000001", DeviceSignature: strings.Repeat("s", 86),
Capabilities: clientCapabilities,
}
client, err := Dial(context.Background(), server.Addr().String(), clientTLS, request)
if err != nil {
cancel()
_ = server.Close()
t.Fatal(err)
}
launch := <-started
if !reflect.DeepEqual(launch.Capabilities.ClientDecode, []string{test.selected}) {
t.Fatalf("provider selected profiles = %v", launch.Capabilities.ClientDecode)
}
_ = client.Close()
cancel()
_ = server.Close()
if err := <-serveDone; err != nil {
t.Fatal(err)
}
})
}
}
func TestRegisteredChannelFramesTraversePublicTransport(t *testing.T) { func TestRegisteredChannelFramesTraversePublicTransport(t *testing.T) {
h := newGatewayTransportHarness(t) h := newGatewayTransportHarness(t)
@@ -525,9 +705,60 @@ func TestProviderTerminationEndsPublicGatewaySession(t *testing.T) {
} }
func TestEncryptedNativeHostTerminationEndsPublicGatewaySession(t *testing.T) { func TestEncryptedNativeHostTerminationEndsPublicGatewaySession(t *testing.T) {
h := newNativeGatewayLifecycleHarness(t, "session-native-terminal")
h.native.handleApolloControlPayload(apolloChannelGeneric, true, sourceSealHostControl(t, h.key, 0, apolloControlTypeTerm, []byte{1, 2, 3, 4}))
tryQueueNativeMedia(h.native, h.native.video, []byte("queued-video"))
tryQueueNativeMedia(h.native, h.native.audio, []byte("queued-audio"))
eventCtx, eventCancel := context.WithTimeout(context.Background(), time.Second)
event, err := h.client.ReceiveProviderEvent(eventCtx)
eventCancel()
if err != nil || event.Kind != ProviderEventTerminated {
t.Fatalf("native provider termination = %#v, %v", event, err)
}
tryQueueNativeMedia(h.native, h.native.video, []byte("new-video"))
tryQueueNativeMedia(h.native, h.native.audio, []byte("new-audio"))
h.assertNoMedia(t)
h.waitReleased(t)
if states := h.reporter.States(); len(states) == 0 || states[len(states)-1].State != ProviderStateTerminated {
t.Fatalf("provider states = %#v", states)
}
}
func TestNativeENetDisconnectQuiescesPublicGatewaySession(t *testing.T) {
h := newNativeGatewayLifecycleHarness(t, "session-native-disconnect")
h.native.handleApolloDisconnect(ErrProviderDisconnected)
tryQueueNativeMedia(h.native, h.native.video, []byte("queued-video"))
tryQueueNativeMedia(h.native, h.native.audio, []byte("queued-audio"))
eventCtx, eventCancel := context.WithTimeout(context.Background(), time.Second)
event, err := h.client.ReceiveProviderEvent(eventCtx)
eventCancel()
if err != nil || event.Kind != ProviderEventDisconnected {
t.Fatalf("native provider disconnect = %#v, %v", event, err)
}
tryQueueNativeMedia(h.native, h.native.video, []byte("new-video"))
tryQueueNativeMedia(h.native, h.native.audio, []byte("new-audio"))
h.assertNoMedia(t)
h.waitReleased(t)
if states := h.reporter.States(); len(states) == 0 || states[len(states)-1].State != ProviderStateDisconnected || states[len(states)-1].CleanupPending {
t.Fatalf("provider states = %#v", states)
}
}
type nativeGatewayLifecycleHarness struct {
native *nativeApolloSession
key []byte
client *Client
admission *oneTimeAdmission
reporter *recordingProviderStateReporter
}
func newNativeGatewayLifecycleHarness(t *testing.T, sessionID string) nativeGatewayLifecycleHarness {
t.Helper()
serverTLS, clientTLS := testTLS(t) serverTLS, clientTLS := testTLS(t)
key := []byte("0123456789abcdef") key := []byte("0123456789abcdef")
native := newNativeApolloSession("session-native-terminal") native := newNativeApolloSession(sessionID)
control, err := newApolloControlCodec(key) control, err := newApolloControlCodec(key)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -557,7 +788,6 @@ func TestEncryptedNativeHostTerminationEndsPublicGatewaySession(t *testing.T) {
t.Fatal(err) t.Fatal(err)
} }
ctx, cancel := context.WithCancel(context.Background()) ctx, cancel := context.WithCancel(context.Background())
defer cancel()
serveDone := make(chan error, 1) serveDone := make(chan error, 1)
go func() { serveDone <- server.Serve(ctx) }() go func() { serveDone <- server.Serve(ctx) }()
request := protocol.TunnelAdmissionRequest{ request := protocol.TunnelAdmissionRequest{
@@ -569,26 +799,37 @@ func TestEncryptedNativeHostTerminationEndsPublicGatewaySession(t *testing.T) {
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
native.handleApolloControlPayload(apolloChannelGeneric, true, sourceSealHostControl(t, key, 0, apolloControlTypeTerm, []byte{1, 2, 3, 4})) t.Cleanup(func() {
eventCtx, eventCancel := context.WithTimeout(context.Background(), time.Second)
event, err := client.ReceiveProviderEvent(eventCtx)
eventCancel()
if err != nil || event.Kind != ProviderEventTerminated {
t.Fatalf("native provider termination = %#v, %v", event, err)
}
select {
case <-admission.released:
case <-time.After(2 * time.Second):
t.Fatal("native termination did not release admission")
}
if states := reporter.States(); len(states) == 0 || states[len(states)-1].State != ProviderStateTerminated {
t.Fatalf("provider states = %#v", states)
}
_ = client.Close() _ = client.Close()
cancel()
_ = server.Close() _ = server.Close()
if err := <-serveDone; err != nil { if err := <-serveDone; err != nil {
t.Fatal(err) t.Errorf("serve: %v", err)
} }
})
return nativeGatewayLifecycleHarness{native: native, key: key, client: client, admission: admission, reporter: reporter}
}
func (h nativeGatewayLifecycleHarness) waitReleased(t *testing.T) {
t.Helper()
select {
case <-h.admission.released:
case <-time.After(2 * time.Second):
t.Fatal("native terminal state did not release admission")
}
}
func (h nativeGatewayLifecycleHarness) assertNoMedia(t *testing.T) {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), 150*time.Millisecond)
defer cancel()
if frame, err := h.client.ReceiveFrame(ctx); err == nil {
t.Fatalf("media crossed after native terminal signal: channel=%d payload=%q", frame.Channel, frame.Payload)
}
}
func tryQueueNativeMedia(session *nativeApolloSession, channel chan ProviderMedia, payload []byte) {
session.enqueueMedia(channel, payload, time.Now())
} }
func TestProviderDisconnectEndsPublicGatewaySessionReconnectable(t *testing.T) { func TestProviderDisconnectEndsPublicGatewaySessionReconnectable(t *testing.T) {
@@ -752,6 +993,7 @@ type oneTimeAdmission struct {
releases atomic.Int64 releases atomic.Int64
released chan struct{} released chan struct{}
streamPolicy protocol.ProviderStreamPolicy streamPolicy protocol.ProviderStreamPolicy
providerWork *protocol.ProviderSessionWork
disableClipboard bool disableClipboard bool
} }
@@ -795,9 +1037,12 @@ func (a *oneTimeAdmission) Admit(context.Context, protocol.TunnelAdmissionReques
} }
func (a *oneTimeAdmission) ProviderWork(_ context.Context, authority protocol.SessionAuthority) (protocol.ProviderSessionWork, error) { func (a *oneTimeAdmission) ProviderWork(_ context.Context, authority protocol.SessionAuthority) (protocol.ProviderSessionWork, error) {
if authority != a.authority { if !reflect.DeepEqual(authority, a.authority) {
return protocol.ProviderSessionWork{}, ErrAdmissionRejected return protocol.ProviderSessionWork{}, ErrAdmissionRejected
} }
if a.providerWork != nil {
return *a.providerWork, nil
}
streamPolicy := a.streamPolicy streamPolicy := a.streamPolicy
if streamPolicy == (protocol.ProviderStreamPolicy{}) { if streamPolicy == (protocol.ProviderStreamPolicy{}) {
streamPolicy = protocol.ProviderStreamPolicy{ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60, Codec: "H264", BitrateKbps: 8000, AudioEnabled: true} streamPolicy = protocol.ProviderStreamPolicy{ResolutionWidth: 1920, ResolutionHeight: 1080, Fps: 60, Codec: "H264", BitrateKbps: 8000, AudioEnabled: true}
+50 -16
View File
@@ -5,6 +5,7 @@ import (
"encoding/xml" "encoding/xml"
"errors" "errors"
"fmt" "fmt"
"strconv"
"strings" "strings"
"sync" "sync"
"time" "time"
@@ -68,6 +69,10 @@ func (i ProviderIdentity) Validate(now time.Time, expected ProviderIdentity) err
type ManagementInfo struct { type ManagementInfo struct {
Identity ProviderIdentity Identity ProviderIdentity
Name string Name string
ServerCodecModeSupport uint32
MaxLumaPixelsHEVC uint64
HasServerCodecModeSupport bool
HasMaxLumaPixelsHEVC bool
} }
func ParseManagementXML(data []byte) (ManagementInfo, error) { func ParseManagementXML(data []byte) (ManagementInfo, error) {
@@ -82,6 +87,8 @@ func ParseManagementXML(data []byte) (ManagementInfo, error) {
NotBefore string `xml:"not_before"` NotBefore string `xml:"not_before"`
NotAfter string `xml:"not_after"` NotAfter string `xml:"not_after"`
Name string `xml:"name"` Name string `xml:"name"`
CodecModes string `xml:"ServerCodecModeSupport"`
MaxHEVCLuma string `xml:"MaxLumaPixelsHEVC"`
} }
decoder := xml.NewDecoder(strings.NewReader(string(data))) decoder := xml.NewDecoder(strings.NewReader(string(data)))
decoder.Strict = true decoder.Strict = true
@@ -108,7 +115,24 @@ func ParseManagementXML(data []byte) (ManagementInfo, error) {
if identity.UniqueID == "" || len(identity.UniqueID) > 128 || len(identity.Fingerprint) > 256 { if identity.UniqueID == "" || len(identity.UniqueID) > 128 || len(identity.Fingerprint) > 256 {
return ManagementInfo{}, ErrProviderMalformed return ManagementInfo{}, ErrProviderMalformed
} }
return ManagementInfo{Identity: identity, Name: document.Name}, nil info := ManagementInfo{Identity: identity, Name: document.Name}
if document.CodecModes != "" {
value, parseErr := strconv.ParseUint(document.CodecModes, 10, 32)
if parseErr != nil {
return ManagementInfo{}, ErrProviderMalformed
}
info.ServerCodecModeSupport = uint32(value)
info.HasServerCodecModeSupport = true
}
if document.MaxHEVCLuma != "" {
value, parseErr := strconv.ParseUint(document.MaxHEVCLuma, 10, 64)
if parseErr != nil {
return ManagementInfo{}, ErrProviderMalformed
}
info.MaxLumaPixelsHEVC = value
info.HasMaxLumaPixelsHEVC = true
}
return info, nil
} }
type RTSPResponse struct { type RTSPResponse struct {
@@ -206,14 +230,20 @@ type ProviderTelemetry struct {
MediaDrops uint64 MediaDrops uint64
} }
type ProviderMedia struct {
Payload []byte
ReceivedAt time.Time
EnqueuedAt time.Time
}
type Provider interface { type Provider interface {
Start(context.Context, LaunchRequest) (ProviderSession, error) Start(context.Context, LaunchRequest) (ProviderSession, error)
} }
type ProviderSession interface { type ProviderSession interface {
Ready(context.Context) error Ready(context.Context) error
Video() <-chan []byte Video() <-chan ProviderMedia
Audio() <-chan []byte Audio() <-chan ProviderMedia
Events() <-chan ProviderEvent Events() <-chan ProviderEvent
Input(context.Context, InputEvent) error Input(context.Context, InputEvent) error
Feedback(context.Context, Feedback) error Feedback(context.Context, Feedback) error
@@ -227,7 +257,7 @@ type ProviderSession interface {
type ApolloBackend interface { type ApolloBackend interface {
Management(context.Context, LaunchRequest) ([]byte, error) Management(context.Context, LaunchRequest) ([]byte, error)
Setup(context.Context, LaunchRequest) ([]byte, error) Setup(context.Context, LaunchRequest, []byte) ([]byte, error)
Open(context.Context, LaunchRequest, RTSPResponse) (ProviderSession, error) Open(context.Context, LaunchRequest, RTSPResponse) (ProviderSession, error)
} }
@@ -268,7 +298,7 @@ func (a *ApolloAdapter) Start(ctx context.Context, request LaunchRequest) (Provi
if request.ProviderIdentity != "" && info.Identity.UniqueID != expected.UniqueID { if request.ProviderIdentity != "" && info.Identity.UniqueID != expected.UniqueID {
return nil, ErrProviderIdentity return nil, ErrProviderIdentity
} }
rawRTSP, err := a.backend.Setup(ctx, request) rawRTSP, err := a.backend.Setup(ctx, request, management)
if err != nil { if err != nil {
return nil, err return nil, err
} }
@@ -352,7 +382,7 @@ func (f *FakeApollo) Management(context.Context, LaunchRequest) ([]byte, error)
return []byte(fmt.Sprintf("<root><unique_id>%s</unique_id><fingerprint>%s</fingerprint><not_before>%s</not_before><not_after>%s</not_after><name>fixture-apollo</name></root>", identity.UniqueID, identity.Fingerprint, f.config.Now.Add(-time.Hour).Format(time.RFC3339), f.config.Now.Add(time.Hour).Format(time.RFC3339))), nil return []byte(fmt.Sprintf("<root><unique_id>%s</unique_id><fingerprint>%s</fingerprint><not_before>%s</not_before><not_after>%s</not_after><name>fixture-apollo</name></root>", identity.UniqueID, identity.Fingerprint, f.config.Now.Add(-time.Hour).Format(time.RFC3339), f.config.Now.Add(time.Hour).Format(time.RFC3339))), nil
} }
func (f *FakeApollo) Setup(context.Context, LaunchRequest) ([]byte, error) { func (f *FakeApollo) Setup(context.Context, LaunchRequest, []byte) ([]byte, error) {
if f.config.Failure == FakeFailureMalformed { if f.config.Failure == FakeFailureMalformed {
return []byte("RTSP/1.0 200 OK\r\n\r\n"), nil return []byte("RTSP/1.0 200 OK\r\n\r\n"), nil
} }
@@ -362,8 +392,8 @@ func (f *FakeApollo) Setup(context.Context, LaunchRequest) ([]byte, error) {
func (f *FakeApollo) Open(_ context.Context, request LaunchRequest, _ RTSPResponse) (ProviderSession, error) { func (f *FakeApollo) Open(_ context.Context, request LaunchRequest, _ RTSPResponse) (ProviderSession, error) {
session := &fakeSession{ session := &fakeSession{
failure: f.config.Failure, failure: f.config.Failure,
video: make(chan []byte, 16), video: make(chan ProviderMedia, 16),
audio: make(chan []byte, 16), audio: make(chan ProviderMedia, 16),
events: make(chan ProviderEvent, 16), events: make(chan ProviderEvent, 16),
clipboardWrites: make(chan string, 1), clipboardWrites: make(chan string, 1),
state: protocol.ProviderState{Version: "1", SessionID: request.SessionID, State: ProviderStateStarting, Channels: []string{"video", "audio", "input", "feedback"}}, state: protocol.ProviderState{Version: "1", SessionID: request.SessionID, State: ProviderStateStarting, Channels: []string{"video", "audio", "input", "feedback"}},
@@ -405,8 +435,8 @@ func (f *FakeApollo) DisconnectProvider() {
type fakeSession struct { type fakeSession struct {
mu sync.Mutex mu sync.Mutex
failure FakeFailure failure FakeFailure
video chan []byte video chan ProviderMedia
audio chan []byte audio chan ProviderMedia
events chan ProviderEvent events chan ProviderEvent
state protocol.ProviderState state protocol.ProviderState
pressed map[string]struct{} pressed map[string]struct{}
@@ -432,8 +462,8 @@ func (s *fakeSession) Ready(ctx context.Context) error {
return nil return nil
} }
func (s *fakeSession) Video() <-chan []byte { return s.video } func (s *fakeSession) Video() <-chan ProviderMedia { return s.video }
func (s *fakeSession) Audio() <-chan []byte { return s.audio } func (s *fakeSession) Audio() <-chan ProviderMedia { return s.audio }
func (s *fakeSession) Events() <-chan ProviderEvent { return s.events } func (s *fakeSession) Events() <-chan ProviderEvent { return s.events }
func (s *fakeSession) EmitEvent(event ProviderEvent) { func (s *fakeSession) EmitEvent(event ProviderEvent) {
@@ -449,15 +479,17 @@ func (s *fakeSession) EmitVideo(payload []byte) {
if s.state.State == ProviderStateTerminating || s.state.State == ProviderStateTerminated || s.state.State == ProviderStateDisconnected { if s.state.State == ProviderStateTerminating || s.state.State == ProviderStateTerminated || s.state.State == ProviderStateDisconnected {
return return
} }
now := time.Now()
media := ProviderMedia{Payload: append([]byte(nil), payload...), ReceivedAt: now, EnqueuedAt: now}
select { select {
case s.video <- append([]byte(nil), payload...): case s.video <- media:
default: default:
select { select {
case <-s.video: case <-s.video:
default: default:
} }
select { select {
case s.video <- append([]byte(nil), payload...): case s.video <- media:
default: default:
} }
} }
@@ -469,15 +501,17 @@ func (s *fakeSession) EmitAudio(payload []byte) {
if s.state.State == ProviderStateTerminating || s.state.State == ProviderStateTerminated || s.state.State == ProviderStateDisconnected { if s.state.State == ProviderStateTerminating || s.state.State == ProviderStateTerminated || s.state.State == ProviderStateDisconnected {
return return
} }
now := time.Now()
media := ProviderMedia{Payload: append([]byte(nil), payload...), ReceivedAt: now, EnqueuedAt: now}
select { select {
case s.audio <- append([]byte(nil), payload...): case s.audio <- media:
default: default:
select { select {
case <-s.audio: case <-s.audio:
default: default:
} }
select { select {
case s.audio <- append([]byte(nil), payload...): case s.audio <- media:
default: default:
} }
} }
+3 -3
View File
@@ -130,7 +130,7 @@ func TestQualificationShortProcessingWritesRawArtifact(t *testing.T) {
func TestQualificationProcessingPreservesPayload(t *testing.T) { func TestQualificationProcessingPreservesPayload(t *testing.T) {
profile := qualificationMediaProfiles()[0] profile := qualificationMediaProfiles()[0]
payload := qualificationPayload(profile) payload := qualificationPayload(profile)
trace, elapsed, err := newQualificationPath(t, profile.BitrateKbps).traverse(t, payload) trace, elapsed, err := newQualificationPath(t, profile, profile.BitrateKbps).traverse(t, payload)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
@@ -190,12 +190,12 @@ func TestQualificationSixImpairmentProfilesTraverseProductionPath(t *testing.T)
func TestQualificationUsesPublicQUICAndProductionPacer(t *testing.T) { func TestQualificationUsesPublicQUICAndProductionPacer(t *testing.T) {
qualificationTraverseProfiles(t, qualificationMediaProfiles()) qualificationTraverseProfiles(t, qualificationMediaProfiles())
evidence, err := qualificationPacerEvidence(filepath.Join(t.TempDir(), "fairness.csv.gz")) evidence, err := qualificationPacerEvidence(t, filepath.Join(t.TempDir(), "fairness.csv.gz"), 2*time.Second, 2*time.Second)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
if len(evidence.PerFlowBytes) != 8 || len(evidence.CapacitySteps) != 2 || if len(evidence.PerFlowBytes) != 8 || len(evidence.CapacitySteps) != 2 ||
len(evidence.Series) != 80 || evidence.RawSamplesSHA256 == "" || evidence.JainIndex < 0.99 { len(evidence.Series) != 6 || evidence.RawSamplesSHA256 == "" || evidence.JainIndex < 0.99 {
t.Fatalf("pacer evidence = %#v", evidence) t.Fatalf("pacer evidence = %#v", evidence)
} }
} }
File diff suppressed because it is too large Load Diff
+93 -27
View File
@@ -9,6 +9,7 @@ import (
"fmt" "fmt"
"io" "io"
"net" "net"
"slices"
"sync" "sync"
"sync/atomic" "sync/atomic"
"time" "time"
@@ -23,7 +24,6 @@ const (
defaultControlLimit = 128 * 1024 defaultControlLimit = 128 * 1024
clientControlBacklog = 64 clientControlBacklog = 64
applicationError = quic.ApplicationErrorCode(0x100) applicationError = quic.ApplicationErrorCode(0x100)
terminalFeedbackDrain = 100 * time.Millisecond
controlFlowID = "control.ack.v1" controlFlowID = "control.ack.v1"
inputFlowID = "input.sequenced.v1" inputFlowID = "input.sequenced.v1"
clipboardFlowID = "clipboard.text.v1" clipboardFlowID = "clipboard.text.v1"
@@ -101,12 +101,15 @@ func NewServer(config ServerConfig) (*Server, error) {
if err := validateServerTLS(config.TLSConfig); err != nil { if err := validateServerTLS(config.TLSConfig); err != nil {
return nil, err return nil, err
} }
if config.Capabilities == (protocol.CapabilityProfile{}) { if capabilityProfileUnset(config.Capabilities) {
config.Capabilities = DefaultCapabilities() config.Capabilities = DefaultCapabilities()
} }
if config.ProviderCapabilities == (protocol.CapabilityProfile{}) { if capabilityProfileUnset(config.ProviderCapabilities) {
config.ProviderCapabilities = DefaultCapabilities() config.ProviderCapabilities = DefaultCapabilities()
} }
if config.Capabilities.Validate() != nil || config.ProviderCapabilities.Validate() != nil {
return nil, ErrNoCapabilityOverlap
}
if config.ProviderProfile == "" { if config.ProviderProfile == "" {
config.ProviderProfile = ProviderProfileApollo config.ProviderProfile = ProviderProfileApollo
} }
@@ -241,6 +244,13 @@ func (s *Server) handleConnection(parent context.Context, connection *quic.Conn)
_ = writeStableError(stream, "no_capability_overlap", err, false) _ = writeStableError(stream, "no_capability_overlap", err, false)
return return
} }
selected, err = selectApolloPolicyCapabilities(work.StreamPolicy, selected)
if err != nil {
_ = s.config.Admission.Release(context.Background(), authority)
s.metrics.AdmissionRejects.Add(1)
_ = writeStableError(stream, "no_capability_overlap", err, false)
return
}
clipboard, err := newClipboardGate(work.ClipboardPolicy, time.Now) clipboard, err := newClipboardGate(work.ClipboardPolicy, time.Now)
if err != nil { if err != nil {
_ = s.config.Admission.Release(context.Background(), authority) _ = s.config.Admission.Release(context.Background(), authority)
@@ -335,13 +345,26 @@ func apolloPolicyMatchesCapabilities(policy protocol.ProviderStreamPolicy, capab
if validateApolloStreamPolicy(policy) != nil || capabilities.Audio != "encoded" { if validateApolloStreamPolicy(policy) != nil || capabilities.Audio != "encoded" {
return false return false
} }
required := apolloPolicyProfile(policy)
return required != "" && slices.Contains(capabilities.ClientDecode, required)
}
func selectApolloPolicyCapabilities(policy protocol.ProviderStreamPolicy, capabilities protocol.CapabilityProfile) (protocol.CapabilityProfile, error) {
if !apolloPolicyMatchesCapabilities(policy, capabilities) {
return protocol.CapabilityProfile{}, ErrNoCapabilityOverlap
}
capabilities.ClientDecode = []string{apolloPolicyProfile(policy)}
return capabilities, nil
}
func apolloPolicyProfile(policy protocol.ProviderStreamPolicy) string {
switch policy.Codec { switch policy.Codec {
case "H264": case "H264":
return capabilities.ClientDecode == "h264-opus" || capabilities.ClientDecode == defaultClientDecode return "h264-opus"
case "HEVC": case "HEVC":
return capabilities.ClientDecode == "hevc-opus" || capabilities.ClientDecode == defaultClientDecode return "hevc-opus"
default: default:
return false return ""
} }
} }
@@ -370,9 +393,12 @@ type gatewaySession struct {
cleanupOnce sync.Once cleanupOnce sync.Once
inputMu sync.Mutex inputMu sync.Mutex
controlWriteMu sync.Mutex controlWriteMu sync.Mutex
outputMu sync.Mutex
pressed map[string]struct{} pressed map[string]struct{}
sequence atomic.Uint32 sequence atomic.Uint32
mediaDrops uint64 mediaDrops uint64
mediaQuiesced bool
terminalSent atomic.Bool
endReason error endReason error
result chan error result chan error
} }
@@ -408,6 +434,13 @@ func (s *gatewaySession) run() {
case s.endReason = <-s.result: case s.endReason = <-s.result:
} }
s.cancel() s.cancel()
if s.terminalSent.Load() {
s.cleanup()
select {
case <-s.connection.Context().Done():
case <-timer.C:
}
}
} }
func (s *gatewaySession) providerEventLoop() { func (s *gatewaySession) providerEventLoop() {
@@ -420,28 +453,32 @@ func (s *gatewaySession) providerEventLoop() {
if !ok { if !ok {
return return
} }
if event.Kind == ProviderEventDisconnected { terminal := event.Kind == ProviderEventTerminated || event.Kind == ProviderEventDisconnected
s.result <- ErrProviderDisconnected if terminal {
return s.outputMu.Lock()
s.mediaQuiesced = true
} }
payload, err := EncodeProviderEvent(event) payload, err := EncodeProviderEvent(event)
if err == nil { if err == nil {
err = s.sendControl(s.sequence.Add(1), payload) err = s.sendControl(s.sequence.Add(1), payload)
} }
if terminal {
s.outputMu.Unlock()
}
if err != nil { if err != nil {
s.result <- err s.result <- err
return return
} }
if event.Kind == ProviderEventTerminated { if terminal {
timer := time.NewTimer(terminalFeedbackDrain) s.terminalSent.Store(true)
select {
case <-s.ctx.Done():
timer.Stop()
return
case <-timer.C:
} }
switch event.Kind {
case ProviderEventTerminated:
s.result <- ErrProviderTerminated s.result <- ErrProviderTerminated
return return
case ProviderEventDisconnected:
s.result <- ErrProviderDisconnected
return
} }
} }
} }
@@ -604,21 +641,21 @@ func (s *gatewaySession) mediaLoop() {
select { select {
case <-s.ctx.Done(): case <-s.ctx.Done():
return return
case payload, ok := <-video: case media, ok := <-video:
if !ok { if !ok {
video = nil video = nil
continue continue
} }
if err := s.sendMedia(ChannelVideo, payload); err != nil { if err := s.forwardMedia(ChannelVideo, media); err != nil {
s.result <- err s.result <- err
return return
} }
case payload, ok := <-audio: case media, ok := <-audio:
if !ok { if !ok {
audio = nil audio = nil
continue continue
} }
if err := s.sendMedia(ChannelAudio, payload); err != nil { if err := s.forwardMedia(ChannelAudio, media); err != nil {
s.result <- err s.result <- err
return return
} }
@@ -627,12 +664,31 @@ func (s *gatewaySession) mediaLoop() {
s.result <- ErrProviderDisconnected s.result <- ErrProviderDisconnected
} }
func (s *gatewaySession) sendMedia(channel byte, payload []byte) error { func (s *gatewaySession) forwardMedia(channel byte, media ProviderMedia) error {
s.outputMu.Lock()
defer s.outputMu.Unlock()
state := s.provider.State().State
if s.mediaQuiesced || state == ProviderStateTerminated || state == ProviderStateDisconnected {
s.mediaQuiesced = true
return nil
}
return s.sendMedia(channel, media)
}
func (s *gatewaySession) sendMedia(channel byte, media ProviderMedia) error {
dequeuedAt := time.Now()
if media.EnqueuedAt.IsZero() || media.EnqueuedAt.After(dequeuedAt) {
media.EnqueuedAt = dequeuedAt
}
if media.ReceivedAt.IsZero() || media.ReceivedAt.After(media.EnqueuedAt) {
media.ReceivedAt = media.EnqueuedAt
}
processingStarted := time.Now() processingStarted := time.Now()
frames, err := FragmentPayload(channel, s.sequence.Add(1), uint64(time.Now().UnixMilli()), payload) frames, err := FragmentPayload(channel, s.sequence.Add(1), uint64(time.Now().UnixMilli()), media.Payload)
if err != nil { if err != nil {
return err return err
} }
var pacingDelay time.Duration
for _, frame := range frames { for _, frame := range frames {
encoded, err := EncodeFrame(frame) encoded, err := EncodeFrame(frame)
if err != nil { if err != nil {
@@ -642,16 +698,18 @@ func (s *gatewaySession) sendMedia(channel byte, payload []byte) error {
if err := s.server.pacer.wait(s.ctx, s.authority.SessionID, len(encoded)); err != nil { if err := s.server.pacer.wait(s.ctx, s.authority.SessionID, len(encoded)); err != nil {
return err return err
} }
s.server.metrics.PacingDelayNanos.Add(uint64(time.Since(pacingStarted))) pacingDelay += time.Since(pacingStarted)
s.server.metrics.QueueDelayNanos.Add(uint64(time.Since(pacingStarted)))
if err := s.connection.SendDatagram(encoded); err != nil { if err := s.connection.SendDatagram(encoded); err != nil {
return err return err
} }
s.server.metrics.MediaPackets.Add(1) s.server.metrics.MediaPackets.Add(1)
s.server.metrics.MediaBytes.Add(uint64(len(encoded))) s.server.metrics.MediaBytes.Add(uint64(len(encoded)))
s.server.metrics.ProcessingDelayNanos.Add(uint64(time.Since(processingStarted)))
s.server.metrics.ProcessingSamples.Add(1)
} }
processingDelay := media.EnqueuedAt.Sub(media.ReceivedAt) + time.Since(processingStarted) - pacingDelay
s.server.metrics.QueueDelayNanos.Add(uint64(dequeuedAt.Sub(media.EnqueuedAt)))
s.server.metrics.ProcessingDelayNanos.Add(uint64(max(processingDelay, 0)))
s.server.metrics.PacingDelayNanos.Add(uint64(pacingDelay))
s.server.metrics.ProcessingSamples.Add(1)
return nil return nil
} }
@@ -799,7 +857,9 @@ func (s *gatewaySession) cleanup() {
} else if err := s.server.config.Admission.Release(cleanupCtx, s.authority); err != nil { } else if err := s.server.config.Admission.Release(cleanupCtx, s.authority); err != nil {
s.server.metrics.ProviderErrors.Add(1) s.server.metrics.ProviderErrors.Add(1)
} }
if !s.terminalSent.Load() {
_ = s.connection.CloseWithError(applicationError, "session closed") _ = s.connection.CloseWithError(applicationError, "session closed")
}
return return
} }
if errors.Is(s.endReason, ErrProviderDisconnected) { if errors.Is(s.endReason, ErrProviderDisconnected) {
@@ -812,7 +872,9 @@ func (s *gatewaySession) cleanup() {
if err := s.server.reportProviderState(cleanupCtx, state); err != nil { if err := s.server.reportProviderState(cleanupCtx, state); err != nil {
s.server.metrics.ProviderErrors.Add(1) s.server.metrics.ProviderErrors.Add(1)
} }
if !s.terminalSent.Load() {
_ = s.connection.CloseWithError(applicationError, "session closed") _ = s.connection.CloseWithError(applicationError, "session closed")
}
}) })
} }
@@ -1001,7 +1063,11 @@ func (c *Client) ReceiveProviderEvent(ctx context.Context) (ProviderEvent, error
if len(payload) > 1024 { if len(payload) > 1024 {
return ProviderEvent{}, ErrProviderMalformed return ProviderEvent{}, ErrProviderMalformed
} }
return DecodeProviderEvent(payload) event, err := DecodeProviderEvent(payload)
if err == nil && (event.Kind == ProviderEventTerminated || event.Kind == ProviderEventDisconnected) {
_ = c.Close()
}
return event, err
} }
func (c *Client) ReceiveClipboard(ctx context.Context) (protocol.GatewayClipboardText, error) { func (c *Client) ReceiveClipboard(ctx context.Context) (protocol.GatewayClipboardText, error) {
@@ -19,11 +19,13 @@ The implementation already contains a source-shaped Apollo fake, native recovery
## Decisions ## Decisions
- Format ANNOUNCE from `ProviderStreamPolicy` using the pinned Moonlight common-c bitrate and codec attributes. H.264 and HEVC with audio enabled are supported; AV1 and audio disabled fail before management/network readiness. - Format ANNOUNCE from `ProviderStreamPolicy` using the pinned Moonlight common-c bitrate and codec attributes. H.264 and HEVC with audio enabled are supported; AV1 and audio disabled fail before management/network readiness.
- Treat the current exact `client_decode` string as the negotiated decode profile. The default advertises the bounded H.264+HEVC set, and provider work must be a member of it. - Advertise ordered registered `hevc-opus` and `h264-opus` profiles and delegate policy-compatible selection to generated Protocol intersection behavior. There is no Data Plane capability grammar.
- Consume existing provider events in the gateway session loop. Termination and disconnect cancel forwarding, then reuse current cleanup/release/reporting machinery and its cleanup-pending result. - Before `/applist` or `/launch`, validate the selected policy against source-backed Apollo `/serverinfo` codec flags and HEVC luma bounds plus reviewed source limits for dimensions, frame rate, bitrate, and audio where Apollo exposes no dynamic field. Reject rather than cap or downgrade.
- Quiesce provider media sockets and the bounded forwarding path before emitting an existing terminal or disconnected event. Reuse current cleanup/release/reporting machinery and its cleanup-pending result; final control delivery has no fixed drain delay.
- On a full audio FEC map, evict the oldest block according to existing block ordering and increment existing drop telemetry. - On a full audio FEC map, evict the oldest block according to existing block ordering and increment existing drop telemetry.
- Carry provider receipt and queue-enqueue timestamps through the existing bounded media value. Queue residence, active processing, and scheduler pacing are sampled separately, once per complete provider media unit.
- Sample existing process counters at heartbeat time; calculate rate from byte and monotonic-time deltas while leaving configured capacity in registration. - Sample existing process counters at heartbeat time; calculate rate from byte and monotonic-time deltas while leaving configured capacity in registration.
- Build qualification on the existing native/provider fixture and public QUIC client path. Production stage observations replace the standalone codec and arithmetic impairment simulator; short smoke gates freeze the wiring, while normative durations remain deferred. - Build qualification on source-shaped pinned-mTLS Apollo management, encrypted RTSP, ENet, and provider UDP plus the public QUIC client path. Per-traversal stage deltas replace the standalone codec/parser and arithmetic impairment simulator; short smoke gates freeze the wiring, while normative durations remain deferred.
- Preserve the production fair-pacer schedule across short host-timer overshoots so - Preserve the production fair-pacer schedule across short host-timer overshoots so
measured allocation can catch up within the already bounded provider queue measured allocation can catch up within the already bounded provider queue
instead of accumulating timer granularity as lost capacity. instead of accumulating timer granularity as lost capacity.
@@ -31,9 +33,10 @@ The implementation already contains a source-shaped Apollo fake, native recovery
## Risks / Trade-offs ## Risks / Trade-offs
- [Apollo cannot represent disabled audio truthfully] → Reject it rather than silently streaming stereo. - [Apollo cannot represent disabled audio truthfully] → Reject it rather than silently streaming stereo.
- [Provider event races with media] → Cancel the session first and let bounded cleanup serialize final release/reporting. - [Provider event races with queued or new media] → Quiesce ingestion and serialize forwarding with terminal event delivery before cleanup.
- [Counter reset or zero elapsed time] → Emit zero measured rate and establish a new baseline. - [Counter reset or zero elapsed time] → Emit zero measured rate and establish a new baseline.
- [Corrected qualification is more expensive] → Run only short smoke tests until the immutable candidate is frozen. - [Corrected qualification is more expensive] → Run only short smoke tests until the immutable candidate is frozen.
- [Apollo exposes incomplete dynamic capability detail] → Use only source-backed fields and explicit reviewed bounds; never infer support by silent capping.
- [Pacer catch-up can emit a short burst after timer overshoot] → Clamp schedule - [Pacer catch-up can emit a short burst after timer overshoot] → Clamp schedule
debt to five milliseconds in addition to the existing 16-packet provider debt to five milliseconds in addition to the existing 16-packet provider
queue. queue.
@@ -4,10 +4,10 @@ Fresh audit evidence shows the gateway ignores the immutable launch policy, leav
## What Changes ## What Changes
- Apply the effective policy to Apollo ANNOUNCE and reject unsupported or downgraded profiles before readiness (P3C-009, P3C-016, P3C-038). - Negotiate registered decode profiles through the shared Protocol intersection, apply the effective policy to Apollo ANNOUNCE, and reject client or provider/source mismatch before launch (P3C-009, P3C-016, P3C-038).
- Convert provider termination/disconnect into bounded tunnel and durable lifecycle transitions while preserving cleanup-pending semantics (P3C-018021, P3C-027). - Quiesce media immediately on provider termination/disconnect, deliver the final typed event reliably, and preserve bounded tunnel and durable lifecycle transitions including cleanup-pending (P3C-018021, P3C-027).
- Evict bounded stale audio FEC blocks so newer recoverable media continues (P3C-001, P3C-026). - Evict bounded stale audio FEC blocks so newer recoverable media continues (P3C-001, P3C-026).
- Derive heartbeat egress and required low-cardinality telemetry from observed counters (P3C-022, P3C-028). - Derive heartbeat egress and semantically separated queue, processing, and pacing observations from the production path (P3C-022, P3C-028).
- Replace standalone processing/impairment simulation with a driver around the source-shaped provider, production queues/pacer/framing, QUIC, and an independent client (P3C-029033, VER-008, VER-010). - Replace standalone processing/impairment simulation with a driver around the source-shaped provider, production queues/pacer/framing, QUIC, and an independent client (P3C-029033, VER-008, VER-010).
## Capabilities ## Capabilities
@@ -8,8 +8,12 @@ The native Apollo backend SHALL derive ANNOUNCE resolution, frame rate, supporte
- **THEN** the encrypted ANNOUNCE carries those settings and the source-backed HEVC and bitrate attributes - **THEN** the encrypted ANNOUNCE carries those settings and the source-backed HEVC and bitrate attributes
### Requirement: Provider policy cannot downgrade ### Requirement: Provider policy cannot downgrade
The gateway MUST reject an invalid, unsupported, audio-disabled, AV1, or capability-mismatched Apollo policy before provider readiness because the current native path cannot truthfully honor those combinations. The gateway MUST use the generated Protocol intersection to select only a registered profile compatible with the immutable policy. It MUST reject invalid, unsupported, no-overlap, downgrade, audio-disabled, AV1, or provider/source-mismatched Apollo policy before `/applist`, `/launch`, or provider readiness because the current native path cannot truthfully honor those combinations.
#### Scenario: Unsupported policy fails closed #### Scenario: Unsupported policy fails closed
- **WHEN** authenticated provider work selects audio disabled, AV1, or a codec outside the negotiated client-decode profile - **WHEN** authenticated provider work selects audio disabled, AV1, a codec outside the registered peer intersection, or a resolution, frame rate, bitrate, audio, or codec combination outside source-backed Apollo support
- **THEN** setup fails before readiness without falling back to H.264, stereo, or another local default - **THEN** setup fails before application discovery or launch without falling back to H.264, stereo, a cap, or another local default
#### Scenario: Independent peers negotiate one registered profile
- **WHEN** a production gateway and independent client advertise overlapping registered H.264 or HEVC profiles
- **THEN** admission selects the first policy-compatible common profile using shared Protocol behavior
@@ -13,3 +13,10 @@ The established authenticated path SHALL expose observed bytes, packets, drops,
#### Scenario: Telemetry snapshot is published #### Scenario: Telemetry snapshot is published
- **WHEN** the gateway emits a heartbeat after forwarding traffic - **WHEN** the gateway emits a heartbeat after forwarding traffic
- **THEN** it carries the bounded process-level observations and no high-cardinality or secret-bearing value - **THEN** it carries the bounded process-level observations and no high-cardinality or secret-bearing value
### Requirement: Production delays have disjoint sample semantics
Queue delay SHALL measure provider-queue residence, processing delay SHALL measure provider recovery plus framing and QUIC handoff work excluding queue and pacing, and pacing delay SHALL measure scheduler waiting only. The gateway SHALL advance processing samples once per complete provider media unit even when it emits multiple Verse frames.
#### Scenario: Known production waits
- **WHEN** one provider media unit has controlled enqueue, processing, and pacing intervals and fragments across multiple frames
- **THEN** each cumulative total reports only its intended interval and exactly one processing sample is retained through authenticated Server persistence
@@ -1,18 +1,18 @@
## MODIFIED Requirements ## MODIFIED Requirements
### Requirement: Fixed media processing qualification ### Requirement: Fixed media processing qualification
The qualification harness SHALL drive the source-shaped provider fixture through Apollo recovery/FEC, bounded production queues, the production fair pacer, Verse framing/QUIC, and an independent client for 1080p60 H.264 at 20 Mbps, 1440p120 HEVC at 50 Mbps, and 4K60 HEVC at 80 Mbps. After a recorded warm-up, the frozen candidate SHALL run each profile for ten wall-clock minutes, preserve encoded payload bytes, retain every monotonic processing sample plus bounded CPU, memory, goroutine, and allocation observations, and report count, min, median, p90, p95, p99, max, mean, standard deviation, timing overhead, and observed bitrate. Any payload mutation or p95 above 5 ms SHALL fail. The qualification harness SHALL drive pinned-mTLS Apollo management, encrypted RTSP, ENet, and provider UDP through native source validation, `readUDPMedia`, recovery/FEC, bounded production queues, the production fair pacer, Verse framing/QUIC, and a public or independent client decoder for 1080p60 H.264 at 20 Mbps, 1440p120 HEVC at 50 Mbps, and 4K60 HEVC at 80 Mbps. After a recorded warm-up, the frozen candidate SHALL run each profile for ten wall-clock minutes, preserve encoded payload bytes, retain every monotonic processing sample plus bounded CPU, memory, goroutine, allocation, and provider-queue observations, and report count, min, median, p90, p95, p99, max, mean, standard deviation, timing overhead, and observed bitrate. Processing begins at complete provider-unit receipt and ends at QUIC handoff, excluding client transit. Any bypass, payload mutation, wall-duration violation, bitrate outside both lower and upper bounds, or p95 above 5 ms SHALL fail.
#### Scenario: Healthy fixed profile #### Scenario: Healthy fixed profile
- **WHEN** a frozen candidate runs one fixed profile for the normative duration - **WHEN** a frozen candidate runs one fixed profile for the normative duration
- **THEN** the harness emits compressed raw path and resource samples plus a summary tied to the exact command, topology, source commit, immutable Protocol version, environment, and payload hash - **THEN** the harness emits compressed raw path and resource samples plus a summary tied to the exact command, topology, source commit, immutable Protocol version, environment, and payload hash
#### Scenario: Processing gate failure #### Scenario: Processing gate failure
- **WHEN** any production path stage is bypassed, payload integrity fails, or measured p95 exceeds 5 ms - **WHEN** any production path stage lacks a per-traversal observation, payload integrity fails, duration or bitrate bounds fail, or measured p95 exceeds 5 ms
- **THEN** the qualification command exits unsuccessfully without recording a passing candidate - **THEN** the qualification command exits unsuccessfully without recording a passing candidate
### Requirement: Bounded impairment qualification ### Requirement: Bounded impairment qualification
The harness SHALL run exactly the baseline, latency, jitter, loss, reorder, and constrained Section 7.2 profiles once against traffic traversing the production gateway path. Baseline SHALL cover all three media profiles and the other profiles SHALL cover 1080p60. Each artifact SHALL retain raw impairment observations and record tool version, exact command/configuration, environment, candidate commit, immutable Protocol version, direction, queue discipline, topology, fixed seed, and observed RTT, jitter, loss, reorder, throughput, drops, and capacity-step statistics. The harness SHALL run exactly the baseline, latency, jitter, loss, reorder, and constrained Section 7.2 profiles once by applying impairment at the source-shaped provider UDP boundary while traffic traverses the production gateway path. Baseline SHALL cover all three media profiles and the other profiles SHALL cover 1080p60. Each artifact SHALL retain raw impairment and queue observations and record tool version, exact command/configuration, environment, candidate commit, immutable Protocol version, direction, queue discipline, topology, fixed seed, and observed RTT, jitter, loss, reorder, throughput, drops, and capacity-step statistics.
#### Scenario: Complete six-profile run #### Scenario: Complete six-profile run
- **WHEN** the frozen candidate runs impairment qualification - **WHEN** the frozen candidate runs impairment qualification
@@ -1,11 +1,11 @@
## ADDED Requirements ## ADDED Requirements
### Requirement: Provider terminal events end forwarding ### Requirement: Provider terminal events end forwarding
Encrypted provider termination and unexpected provider disconnect SHALL stop media forwarding, close the Verse tunnel within a bounded interval, release the session reservation, and report the appropriate durable provider/session state. Encrypted provider termination and unexpected provider disconnect SHALL quiesce provider ingestion and queued/new media forwarding before the existing reliable typed terminal event is delivered, close the Verse tunnel within a bounded interval, release the session reservation, and report the appropriate durable provider/session state. A fixed drain delay MUST NOT stand in for reliable control delivery.
#### Scenario: Host termination closes the tunnel #### Scenario: Host termination closes the tunnel
- **WHEN** the native provider emits an authenticated termination event - **WHEN** the native provider emits an authenticated termination event
- **THEN** no later provider media is delivered and the client tunnel, reservation, and durable lifecycle transition complete - **THEN** queued and newly injected media cannot cross the Verse transport after observation, and the client tunnel, reservation, and durable lifecycle transition complete
#### Scenario: Unexpected provider disconnect is reconnectable #### Scenario: Unexpected provider disconnect is reconnectable
- **WHEN** required provider transport disconnects without acknowledged termination - **WHEN** required provider transport disconnects without acknowledged termination
@@ -1,20 +1,21 @@
## 1. Native Policy and Media ## 1. Native Policy and Media
- [x] 1.1 Drive supported immutable policy values into encrypted Apollo ANNOUNCE - [x] 1.1 Drive supported immutable policy values into encrypted Apollo ANNOUNCE
- [x] 1.2 Reject unsupported and capability-mismatched policy before readiness - [x] 1.2 Negotiate registered profiles through shared Protocol intersection behavior
- [x] 1.3 Evict oldest incomplete audio FEC state and pass sustained-loss relay regression - [x] 1.3 Reject unsupported client or provider/source policy before `/applist`, `/launch`, or readiness
- [x] 1.4 Evict oldest incomplete audio FEC state and pass sustained-loss relay regression
## 2. Lifecycle and Telemetry ## 2. Lifecycle and Telemetry
- [x] 2.1 Close forwarding and report durable state on provider termination and disconnect - [x] 2.1 Quiesce queued and new media before terminal event delivery and report durable state
- [x] 2.2 Preserve cleanup-pending on terminal cleanup failure - [x] 2.2 Preserve cleanup-pending on terminal cleanup failure
- [x] 2.3 Report measured heartbeat egress and required bounded telemetry - [x] 2.3 Report measured heartbeat egress and separately sampled queue, processing, and pacing telemetry
## 3. Qualification Path ## 3. Qualification Path
- [x] 3.1 Add a red-to-green end-to-end production-path smoke gate - [x] 3.1 Add a red-to-green native UDP-to-public-client production-path smoke gate with per-traversal stage evidence
- [x] 3.2 Remove duplicate processing and impairment simulation - [x] 3.2 Remove direct native internals, private QUIC/parser, and arithmetic impairment shortcuts
- [x] 3.3 Retain raw processing, impairment, fairness, cap, convergence, and resource observations - [x] 3.3 Retain raw processing, impairment, fairness, cap, convergence, queue, and resource observations
- [x] 3.4 Pass short fixed-profile, impairment, fairness, race, parser fuzz, and resource smoke checks - [x] 3.4 Pass short fixed-profile, impairment, fairness, race, parser fuzz, and resource smoke checks
## 4. Immutable Freeze ## 4. Immutable Freeze