feat(stream): expose upstream metadata headers

[stackia]

Summary

• expose a stable, allowlisted set of R2H-* upstream metadata headers for RTSP, multicast, FCC, MPEG-TS, and JPEG snapshot responses
• add control-only RTSP HEAD probing through OPTIONS and DESCRIBE, while keeping multicast and FCC HEAD requests free of media joins or control requests
• report negotiated RTSP transport, confirmed payload framing, playback metadata, SDP duration, and FCC startup status when those values are known
• document the HTTP contract in both Chinese and English and add focused RTSP, multicast, FCC, snapshot, proxy, CORS, and configuration coverage

Motivation

Downstream HTTP clients need a consistent way to understand how a stream was sourced and negotiated without exposing sensitive upstream RTSP details or requiring a media parser. HEAD requests should provide all metadata available from static configuration or SDP without creating a media stream.

Implementation notes

Metadata is stored in a fixed-size stream_metadata_t and frozen when response headers are emitted. Unknown or unconfirmed values are omitted. RTSP HEAD probes stop after DESCRIBE and synchronously release the control connection before queuing the HTTP response, preventing later upstream hangups from dropping the response. The implementation intentionally does not expose FEC state or R2H-Metadata-Version.

Validation

• CMake build
• Clang format check
• Ruff format and lint checks
• E2E collection: 549 tests
• RTSP transport: 12 passed
• RTSP miscellaneous: 12 passed
• focused Metadata/HEAD RTSP tests: 5 passed
• VitePress documentation build

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Documentation preview

The documentation preview has been deployed for this pull request.

• Preview: https://thankful-water-0a297bf00-684.eastasia.1.azurestaticapps.net
• Commit: bdf5fb8

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 620d21eb22

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Scope SDP payload detection to selected media track

When a DESCRIBE SDP has multiple m= sections and a later track advertises MP2T, this sets R2H-Upstream-Payload even though the code immediately below chooses the first media-level a=control for SETUP. For streams whose first track is H264/audio/etc. and a later track is MP2T, HEAD responses and early stream headers can incorrectly report mp2t-rtp for the proxied track; the payload probe should be limited to the same media section selected for SETUP.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Defer FCC status until media is actually output

When an FCC unicast packet is merely received, this marks status active before stream_process_rtp_payload and the reorder buffer have actually delivered any bytes to the client. If those unicast packets are still buffered or discarded and multicast supplies the first bytes that trigger the HTTP headers, for example after fallback during the reorderer's initial collection, the response will still say R2H-FCC-Status: active instead of fallback; defer the status choice until the origin that actually queues the first media.

Useful? React with 👍 / 👎.