//! The **amputation seam**: FFmpeg's bytes leave here, copied once,
//! as Rust-owned memory.
//!
//! An `AVPacket`'s payload and an `AVFrame`'s planes both live in
//! `AVBufferRef`s — FFmpeg's own refcounted allocations. Through 0.8
//! this crate handed those out directly, wrapped in an `FfmpegBuffer`
//! whose `AsRef<[u8]>` pointed straight into libavcodec's memory. That
//! type is gone. Every byte that crosses this boundary is now copied
//! into an [`FfmpegBytes`], which is what the core's
//! [D-seat amputation contract][law] requires: owned, `Send + Sync`,
//! clone-is-a-refcount-bump, and with no FFmpeg lifetime riding along.
//!
//! What is left in this module is everything the copy still has to
//! *judge*. A packet's payload has to be proved to lie inside the
//! buffer that owns it before a byte of it is read, its side data has
//! to be carried whole or refused, and its flags have to fit the
//! portable set — so [`PacketBufferError`] and its payload structs
//! outlive the buffer type they were written for. The bounds check in
//! particular matters *more* now, not less: 0.8 formed a view over the
//! claimed range, 0.9 reads it.
//!
//! # The one thing the amputation costs
//!
//! The `Arc<[u8]>` behind [`FfmpegBytes`] has no fallible constructor
//! on stable Rust, so the copy itself aborts on allocation failure
//! rather than returning an error.
//! Everything that bounds *how much* can be asked for — the side-data
//! entry and byte caps, the plane-geometry checks — is unchanged and
//! still runs before any allocation, so a hostile stream cannot reach
//! that abort by demanding memory; only a genuinely exhausted
//! allocator can.
//!
//! [`payload_of`] is where the per-packet half of that bounding lives:
//! every packet body this crate copies passes through it, and it
//! refuses an over-budget claim before reading a byte. See
//! [`crate::limits`] for the budgets and their defaults.
//!
//! # The funnel's accounting
//!
//! Every [`FfmpegBytes`] in this crate is built by
//! [`FfmpegBytes::copy_from_slice`], [`FfmpegBytes::from_rows`] or
//! [`FfmpegBytes::empty`], and **every one of those call sites is
//! bounded before it allocates**. The table is kept here, beside the
//! constructors, so that a new exit has to answer the question the
//! existing ones already answered — the discipline is inherited by
//! being written down where the next author will be standing.
//!
//! Three review rounds found bypasses that each looked like an
//! exception: a plane path with no ceiling, an attachment whose
//! payload was copied by `avcodec_parameters_copy` before its budget
//! was charged, a resampler amplifying a small input into a huge
//! output, and then `coded_side_data` — a third heap seat on the same
//! wholesale parameter copy, where a MOV `prof` atom puts an ICC
//! profile. None of them were exceptions. They were rows nobody had
//! written down.
//!
//! The third one is why the table below has a section it did not need
//! at first. `FfmpegBytes` is not the only place this crate copies
//! attacker-sized bytes: `AVCodecParameters` has heap seats of its own,
//! and the wholesale FFI copy that used to duplicate them took every
//! one — including any this crate had never enumerated. That copy is
//! gone; see
//! [`bounded_clone_parameters`](crate::extras::bounded_clone_parameters).
//!
//! | construction site | what it carries | what bounds it |
//! |---|---|---|
//! | [`payload_of`] | any packet's payload | its `budget` argument — [`PacketLimits::max_packet_bytes`](crate::PacketLimits::max_packet_bytes) for timed packets, [`DemuxLimits::max_attachment_bytes`](crate::DemuxLimits::max_attachment_bytes) for attachments — judged against the declared `size` before a byte is read |
//! | `convert::copy_out_planes`, tight stride | one video or image plane | [`FrameLimits::max_pixels`](crate::FrameLimits::max_pixels) and [`FrameLimits::max_frame_bytes`](crate::FrameLimits::max_frame_bytes), both in a judge-pass that runs before any plane is allocated; `max_pixels` also reaches libavcodec |
//! | `convert::copy_out_planes`, padded stride | one compacted plane, via [`FfmpegBytes::from_rows`] | the same pre-pass |
//! | `convert::av_frame_to_audio_frame` | one audio plane | `max_frame_bytes`, checked over `plane_bytes × plane_count` before the loop |
//! | `convert::collect_side_data` | one frame side-data entry | `SIDE_DATA_MAX_ENTRIES` (64) and `SIDE_DATA_MAX_TOTAL_BYTES` (256 KiB), plus `try_reserve_exact` |
//! | `boundary::packet_side_data` | one packet side-data entry | the same two caps, as refusals rather than truncation |
//! | `convert::av_subtitle_to_subtitle_frame`, text | concatenated cue text | `SUBTITLE_MAX_TEXT_BYTES_PER_RECT` (64 KiB), `SUBTITLE_MAX_TEXT_TOTAL_BYTES` (256 KiB), `SUBTITLE_MAX_RECTS` (64) |
//! | …, bitmap | one paletted rect | `SUBTITLE_MAX_BITMAP_BYTES_PER_RECT` (16 MiB), `SUBTITLE_MAX_BITMAP_TOTAL_BYTES` (32 MiB), `SUBTITLE_MAX_RECTS` |
//! | …, palette | an RGBA palette | structurally fixed at 256 × 4 bytes by the format |
//! | `demuxer::extradata_payload` | a synthesized attachment (a font) | `demuxer::admit_attachments`, which charges every attachment in the file — per-attachment **and** aggregate — before the track loop allocates anything; re-checked here against the per-attachment ceiling |
//! | `demuxer::attached_pic_payload` | a hoisted cover-art packet | the same admission pass, then `payload_of`'s budget |
//! | `resampler::finish_output` | one converted audio plane | `FfmpegResampler::check_output_bytes`, against `max_frame_bytes`, run before the output `AVFrame` is allocated |
//! | every [`FfmpegBytes::empty`] site | nothing | structurally zero: placeholder plane slots, a payload-less packet, a null palette, a marker side-data entry |
//!
//! # The other heap this crate copies
//!
//! `AVCodecParameters` is not an [`FfmpegBytes`] and never passes
//! through this module, but it is the same class of exposure — three
//! heap seats, all sized by the file — so its rows belong in the same
//! accounting.
//!
//! | construction site | what it carries | what bounds it |
//! |---|---|---|
//! | [`bounded_clone_parameters`](crate::extras::bounded_clone_parameters), `extradata` | SPS/PPS and codec headers | [`DemuxLimits::max_codec_parameter_bytes`](crate::DemuxLimits::max_codec_parameter_bytes), measured by `measure_parameters` before the copy |
//! | …, `coded_side_data` | the descriptor array and each entry's payload — a MOV `prof` atom's ICC profile among them | the same seat, counting the array as well as the payloads |
//! | …, `ch_layout` custom map | a channel map | the same seat; the one FFmpeg call left on this path (`av_channel_layout_copy`) copies exactly this field, at a size measured first |
//! | `demuxer::admit_streams` | nothing — it only measures | runs over **every** stream before the track loop clones anything, and charges the whole-file [`max_total_codec_parameter_bytes`](crate::DemuxLimits::max_total_codec_parameter_bytes) |
//! | `decoder::build_codec_context` → `avcodec_parameters_to_context` | the same three seats, copied *into* an `AVCodecContext` | **the choke point**: measured and admitted against [`DecoderLimits::max_codec_parameter_bytes`](crate::DecoderLimits::max_codec_parameter_bytes) right there. Every decoder in this crate opens through this function — the four session `open`s, the HW probe's `build_state`, its per-backend advances, the software fallback — and none of them reaches `avcodec_parameters_to_context` any other way |
//! | `image::FfmpegImageDecoder::decode` → `boundary::try_packet_copy` | the caller's compressed bytes, duplicated into an `AVPacket` | [`DecoderLimits::max_image_input_bytes`](crate::DecoderLimits::max_image_input_bytes), defaulting to the attachment family so the direct road is no more permissive than the demuxed one |
//! | `boundary::ffmpeg_packet_from_{video,audio,subtitle}_packet` → `try_packet_copy` | the caller's compressed bytes, duplicated into an `AVPacket` — **the send leg** | [`DecoderLimits::max_packet_bytes`](crate::DecoderLimits::max_packet_bytes), judged before the allocation. The same seat the receive leg (`payload_of`) judges, so a byte count refused coming out of a container is refused going into a decoder |
//! | still `pal8` palette plane | a fixed `AVPALETTE_SIZE` run | the **format**, not a seat: 256 × `AV_PIX_FMT_RGB32`, always, with no number a file gets to choose |
//!
//! # The rule
//!
//! **A carrier whose size comes from a file is bounded by a seat in
//! [`crate::limits`]; a carrier whose size is a property of a format is
//! bounded by that format.** There is no third kind, and a site that
//! looks like one has not been thought about yet.
//!
//! And the corollary the third round bought: **no code path hands
//! attacker-sized data to a wholesale FFI copy** — a copy that
//! duplicates every field of a struct duplicates the fields nobody
//! enumerated, which is a budget bypass that arrives with the next
//! FFmpeg release rather than with the next commit.
//!
//! # The substrate's knobs, and where this crate stops
//!
//! Everything above is **tier one** of the [resource governance
//! contract][gov]: allocations this crate makes itself, each bounded by
//! a named seat or by a format. This table is that tier's proof.
//!
//! Tier two is the other half — FFmpeg's own resource knobs, set at
//! every point libavcodec and libavformat offer one. They bound
//! allocations this crate does not make and could not otherwise see:
//!
//! | knob | where it is set | what it bounds |
//! |---|---|---|
//! | `AVCodecContext.max_pixels` | every opened decoder | the caller's pixel limit, **verbatim**, applied by `ff_set_dimensions` to the raw dimensions. Extent, not cost: what a frame *costs* is the byte judge's question, two rows down |
//! | the `get_format` coded-dims ask | the hardware road | the **pool's own declared extent**, asked of `avcodec_get_hw_frames_parameters` before the pool is initialised — `max_pixels` is applied to the *display* dims, which a cropped stream can make 2000x smaller |
//! | the `get_format` byte judge | the hardware road | the **pool's** cost, priced through [`crate::footprint`] against `max_frame_bytes`. **Fails closed**: a pool that will not declare its dimensions and layout is a pool that cannot be judged, and the codec-alignment fallback that used to stand in could answer *smaller* than the pool it was standing in for |
//! | the `get_buffer2` byte judge | every software decode | what the allocator will actually take for this frame — pictures and audio both, priced through [`crate::footprint`] against the caller's own `max_frame_bytes`, carried in the codec context's callback state |
//! | the pre-transfer judge | every `av_hwframe_transfer_data` | the CPU destination a hardware download allocates, priced at the frames-context pool dims — folding **every** candidate format FFmpeg may pick, priceable or not, since FFmpeg does the picking |
//! | `probesize` / `formatprobesize` | both demux entrypoints | what the format probe and stream analysis may consume |
//! | `max_streams` | both demux entrypoints | the `AVStream` array a header can conjure |
//! | the `AVIOContext` byte meter | the **reader** demux entrypoint | total bytes libavformat is handed, hard — past the budget the reader stops answering |
//!
//! Two of those knobs used to carry *translated* byte ceilings —
//! `max_pixels` as `min(the caller's limit, bytes / 16)` and
//! `max_samples` as `bytes / 8` — so that the byte budget could bite
//! before libavcodec allocated. Both translations charged every stream
//! the worst format in existence, and both over-refused ordinary media:
//! a 1920x1080 `yuv420p` frame under a 4 MiB budget, a 6-channel `s16`
//! frame under 64 KiB. They are gone. The byte budget is enforced by
//! the `get_buffer2` judge, which is *itself* a pre-allocation seat —
//! `get_buffer2` **is** the allocation — and prices the frame's real
//! format at its real dimensions. An exact judge at the allocation
//! beats an approximate one before it.
//!
//! Where a layout cannot be priced at all, these judges charge
//! [`crate::footprint::video_frame_bytes_upper_bound`] — the same
//! dimension alignment and per-plane overhead at the widest per-pixel
//! rate the census finds — rather than a bare `w * h * rate`, which
//! omits both and could land *below* the accurate path it was standing
//! in for. A conservative fallback that can under-state is not
//! conservative.
//!
//! **These are defense in depth, not a proof.** Each bounds what it was
//! built to bound; together they cover every interposition point FFmpeg
//! exposes, which is not the same as covering FFmpeg.
//!
//! ## What the demux seats cannot reach, and why they exist anyway
//!
//! `avformat_open_input` and `avformat_find_stream_info` build the
//! attached picture, the extradata and the coded side data out of the
//! file themselves. The attachment and parameter seats in the table
//! above therefore measure this crate's *copies* of buffers libavformat
//! has already allocated — too late, by construction, to have prevented
//! the original.
//!
//! A parser cannot allocate from bytes it was never handed, so the
//! input is bounded instead: that is what the probe knobs and the byte
//! meter are for. What is **not** bounded is allocation *amplification*
//! inside a parser — a container can describe, in a handful of bytes, a
//! structure whose in-memory form is far larger, and nothing outside
//! libavformat can observe it happen. Bounding that output is the
//! substrate's own hardening territory; FFmpeg keeps `max_streams`,
//! `max_index_size` and `max_picture_buffer` for it, and this crate
//! sets the first.
//!
//! The hard meter also does not reach the **path** entrypoint: it needs
//! an `AVIOContext` this crate owns, and a path is opened by
//! libavformat's own protocol layer. The probe knobs still apply there;
//! a caller who wants the meter on a file opens it as a reader.
//!
//! That gap is **tier three**, and it is named rather than hedged: see
//! the [contract][gov] for the boundary and for the OS-level instrument
//! a deployment needing a hard memory bound puts underneath all of
//! this. This crate is not a hypervisor for FFmpeg, and its seats
//! compose with that instrument rather than replacing it.
//!
//! [gov]: mediadecode::adapter#the-resource-governance-contract
//!
//! And the capstone, which is what every seat in this table is finally
//! for: **a judge must dominate the allocator's arithmetic, not the
//! payload's.** A budget compared against what the bytes weigh is not a
//! budget on what will be spent — see [`crate::footprint`] for the
//! measured gap and for the two judges that were caught paying it.
//!
//! And the corollary the ninth bought, which is about *whether* to
//! carry at all rather than how much: **a payload that carries
//! addresses instead of bytes is uncarriable.** `AV_PKT_FLAG_TRUSTED`
//! marks one — the wrapped-`AVFrame` producers use it for a body that
//! is an `AVFrame` pointer structure — and copying it mints a carrier
//! that passes every property this table exists to guarantee and
//! dangles the moment its source drops. It is refused on both legs
//! ([`payload_of`] and the reverse builders), because either alone
//! leaves the loop open. See [`TrustedPayload`].
//!
//! And the corollary the seventh bought, about the *inputs* to every
//! guard above rather than the guards themselves: **a number a file
//! chooses is judged or refused, never clipped.** A seat that bounds a
//! byte product still trusts the fields the product is computed from,
//! so a clamped sample count or channel count does not trip any budget
//! — it produces a smaller, plausible frame that no ceiling has any
//! reason to stop. Two of those were live on the audio path (a floored
//! negative `nb_samples`, a channel count clipped to `u8::MAX`), and
//! both turned a malformed header into a well-formed-looking frame,
//! which is strictly worse than an error. The audio road now carries no
//! lossy clamp; the one floor left, `sample_rate`, is censused at its
//! site with the reason it is metadata and sizes nothing.
//!
//! [law]: mediadecode::adapter#the-d-seat-amputation-contract
use std::{
fmt,
sync::{Arc, OnceLock},
};
use derive_more::{IsVariant, TryUnwrap, Unwrap};
/// The bytes every packet and frame this crate produces are carried in.
///
/// Owned, `Send + Sync`, `'static`, and clone-is-a-refcount-bump: the
/// core's [D-seat amputation contract][law], satisfied. Nothing inside
/// reaches back into libavcodec.
///
/// # Why it is opaque
///
/// The obvious spelling was the bare `Arc<[u8]>` this type wraps, and
/// 0.9.0's first cut used it. It is opaque for one reason, and the
/// reason is not aesthetics:
///
/// **`Arc<[u8]>` is one storage strategy, and it is not going to be the
/// only one.** Every exit currently allocates, copies, and frees per
/// frame; a decode loop at 4K is asking the global allocator for eight
/// megabytes sixty times a second and handing it back. The recorded
/// answer is a plane pool — reusable slabs handed out at the boundary
/// and returned when the last consumer drops them
/// ([issue #35](https://github.com/findit-studio/mediadecode/issues/35)).
/// A pooled slab is a different carrier with the same contract: still
/// owned, still `Send + Sync`, still refcount-cloned, still holding no
/// FFmpeg lifetime.
///
/// If the carrier were `Arc<[u8]>` in the public aliases, adding the
/// pool would change the type of every frame and every packet in the
/// crate — a breaking release for a change consumers cannot observe.
/// Behind this newtype it is a new arm of a **private** enum: no
/// signature moves, no consumer recompiles differently, and the
/// `AsRef<[u8]>` a consumer actually programs against is unchanged.
/// That extension point *is* this type's justification for existing.
///
/// The enum has exactly one arm today. It gains the second when the
/// pool is built and not before — this codebase does not carry members
/// nothing can produce.
///
/// [law]: mediadecode::adapter#the-d-seat-amputation-contract
#[derive(Clone, Default, PartialEq, Eq, Hash)]
pub struct FfmpegBytes(Inner);
/// The storage behind [`FfmpegBytes`]. **Private, and the point.**
///
/// One arm today; see the type's own docs for the arm that is coming
/// and why it can arrive without a breaking release.
#[derive(Clone, PartialEq, Eq, Hash)]
enum Inner {
/// A refcounted slice, allocated by the copy at the boundary.
Shared(Arc<[u8]>),
}
impl Default for Inner {
#[inline]
fn default() -> Self {
Self::Shared(shared_empty())
}
}
impl FfmpegBytes {
/// Copies `bytes` into a fresh carrier.
///
/// **The copy site.** Every exit in this crate lands here or on
/// [`Self::empty`], so "one copy at the boundary" is a property of
/// one constructor rather than a promise thirty call sites keep —
/// and it is the one place a future pooled arm has to be taught
/// about.
///
/// Public because the reverse direction needs it: a consumer
/// building a packet to feed back into a decoder has bytes and needs
/// a carrier, and the alternative is an opaque type nobody outside
/// this crate can construct.
///
/// A zero-length copy lands on the shared empty allocation rather
/// than minting its own.
#[inline]
pub fn copy_from_slice(bytes: &[u8]) -> Self {
if bytes.is_empty() {
return Self::empty();
}
Self(Inner::Shared(Arc::from(bytes)))
}
/// The zero-length carrier, shared.
///
/// Placeholder plane slots and payload-less packets are frequent — a
/// video frame allocates four slots and populates one to three of
/// them — and each would otherwise be its own `Arc` header
/// allocation. One empty allocation for the process, cloned by
/// refcount, instead.
#[inline]
pub fn empty() -> Self {
Self(Inner::Shared(shared_empty()))
}
/// Builds a carrier of `rows * row_bytes` bytes by writing each row
/// in turn — **one allocation, no staging buffer**.
///
/// This is the road a padded plane takes. FFmpeg lays such a plane
/// out `linesize` bytes per row while only the first `row_bytes` of
/// each are the decoder's output, so the copy has to be row-wise and
/// the destination is contiguous. The obvious spelling — build a
/// `Vec`, then `Arc::from` it — allocates the whole plane **twice**
/// and copies it twice, so a 250 MiB frame peaks at 750 MiB counting
/// FFmpeg's own. Writing the rows straight into
/// `Arc::new_uninit_slice` leaves the unavoidable 2×: FFmpeg's plane
/// and ours.
///
/// `row(i)` must answer a slice of exactly `row_bytes`; a shorter or
/// longer one is a bug in the caller's geometry and panics rather
/// than leaving the tail of the allocation uninitialised. That
/// assertion is what discharges the initialisation contract for the
/// `assume_init` below: the loop visits every row, each row fills its
/// full width, and `rows * row_bytes` is the whole allocation.
///
/// Crate-internal: the public face is [`Self::copy_from_slice`], and
/// this shape only makes sense to a caller that already holds a
/// strided picture.
///
/// # Panics
///
/// If `rows * row_bytes` overflows `usize`, or if `row(i)` answers a
/// slice that is not `row_bytes` long. Callers reach this only after
/// the geometry has been validated and the total checked against
/// [`FrameLimits`](crate::FrameLimits), so both are unreachable from
/// input.
pub(crate) fn from_rows<'a>(
rows: usize,
row_bytes: usize,
mut row: impl FnMut(usize) -> &'a [u8],
) -> Option<Self> {
let len = rows.checked_mul(row_bytes)?;
if len == 0 {
return Some(Self::empty());
}
let mut uninit = Arc::<[u8]>::new_uninit_slice(len);
{
let slots =
Arc::get_mut(&mut uninit).expect("the allocation was made here and has not been shared");
for index in 0..rows {
let source = row(index);
if source.len() != row_bytes {
// A length that arrives from a caller is an input, not a
// promise: refuse rather than copy `row_bytes` out of a
// shorter slice. The half-built `Arc` drops with this
// return, and every byte of it is still `MaybeUninit`.
return None;
}
let start = index * row_bytes;
// `MaybeUninit<u8>` has the same layout as `u8`, so the source
// slice can be viewed as one and copied wholesale.
let destination = &mut slots[start..start + row_bytes];
// SAFETY: `&[u8]` and `&[MaybeUninit<u8>]` have identical
// layout, and the cast is read-only on the source side.
let source: &[core::mem::MaybeUninit<u8>] = unsafe {
core::slice::from_raw_parts(
source.as_ptr().cast::<core::mem::MaybeUninit<u8>>(),
row_bytes,
)
};
destination.copy_from_slice(source);
}
}
// SAFETY: the loop above wrote every one of the `rows * row_bytes`
// slots — `rows` iterations, each filling exactly `row_bytes`
// consecutive bytes starting at `index * row_bytes`, with the
// length of each source row checked before the copy and the whole
// gather abandoned if one disagreed. Nothing in the allocation is
// left uninitialised on this road.
Some(Self(Inner::Shared(unsafe { uninit.assume_init() })))
}
/// The bytes, as a slice.
///
/// The same answer [`AsRef::as_ref`] gives; inherent so a caller
/// reaching through a `&FfmpegBytes` does not have to name the trait.
#[inline]
pub fn as_slice(&self) -> &[u8] {
match &self.0 {
Inner::Shared(bytes) => bytes,
}
}
/// Number of bytes carried.
#[inline]
pub fn len(&self) -> usize {
self.as_slice().len()
}
/// `true` when this carries no bytes.
#[inline]
pub fn is_empty(&self) -> bool {
self.as_slice().is_empty()
}
/// `true` when both handles name the same allocation — a clone of
/// one another, rather than two copies that happen to be equal.
///
/// The property the amputation contract is really about: `Clone` on
/// a message is a refcount bump. `PartialEq` answers a different
/// question (do these hold the same bytes), and a test that wants to
/// prove the clone did not copy has to ask this one.
#[inline]
pub fn ptr_eq(&self, other: &Self) -> bool {
match (&self.0, &other.0) {
(Inner::Shared(a), Inner::Shared(b)) => Arc::ptr_eq(a, b),
}
}
}
impl AsRef<[u8]> for FfmpegBytes {
#[inline]
fn as_ref(&self) -> &[u8] {
self.as_slice()
}
}
impl fmt::Debug for FfmpegBytes {
/// Length only, never the bytes.
///
/// A derived `Debug` would print a decoded 4K plane one integer at a
/// time; this type is reached from the derived `Debug` of every
/// packet, frame and side-data entry in the crate, so the terse form
/// is the one that keeps those useful. Mirrors what `FfmpegBuffer`'s
/// own hand-written `Debug` did through 0.8.
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("FfmpegBytes")
.field("len", &self.len())
.finish()
}
}
/// The process-wide empty `Arc`, so a zero-length carrier costs a
/// refcount bump rather than an allocation.
fn shared_empty() -> Arc<[u8]> {
static EMPTY: OnceLock<Arc<[u8]>> = OnceLock::new();
EMPTY.get_or_init(|| Arc::from(&[][..])).clone()
}
/// Payload for [`PacketBufferError::PacketTooLarge`].
///
/// A packet's payload is larger than the budget in force.
///
/// Refused **before** the copy: 0.8 answered a claimed payload with a
/// refcount, so an absurd `size` cost nothing; 0.9 answers it with an
/// allocation, so the claim has to be judged first.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("a {bytes}-byte packet payload exceeds the {limit}-byte budget")]
pub struct PacketTooLarge {
bytes: usize,
limit: usize,
}
impl PacketTooLarge {
/// Constructs a `PacketTooLarge` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(bytes: usize, limit: usize) -> Self {
Self { bytes, limit }
}
/// The payload length the packet declared.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn bytes(&self) -> usize {
self.bytes
}
/// The budget in force.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn limit(&self) -> usize {
self.limit
}
}
/// Payload for [`PacketBufferError::Bounds`].
///
/// The payload does not lie inside the packet's own buffer.
/// `AVPacket` guarantees it does; a packet that says otherwise is
/// malformed, and wrapping it would hand out a view over memory the
/// buffer does not own.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("a {len}-byte payload at offset {offset} does not lie inside a {size}-byte buffer")]
pub struct Bounds {
offset: usize,
len: usize,
size: usize,
}
impl Bounds {
/// Constructs a `Bounds` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(offset: usize, len: usize, size: usize) -> Self {
Self { offset, len, size }
}
/// Where the payload starts inside the buffer.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn offset(&self) -> usize {
self.offset
}
/// The payload's length in bytes.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn len(&self) -> usize {
self.len
}
/// `true` when the payload is zero bytes long.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn is_empty(&self) -> bool {
self.len == 0
}
/// The buffer's own length in bytes.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn size(&self) -> usize {
self.size
}
}
/// Payload for [`PacketBufferError::SideDataEntries`].
///
/// A packet declares more side-data entries than this crate will
/// walk, or a negative count.
///
/// The cap bounds the work a crafted packet can demand *before* it is
/// refused. It cannot trip on anything FFmpeg's own packet API
/// produces: both `av_packet_new_side_data` and
/// `av_packet_add_side_data` replace an entry of the same type, so a
/// packet carries at most one entry per named type — forty-three in
/// this build, and the cap tracks that number if it ever grows past
/// the floor.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("a packet declaring {count} side-data entries cannot be carried (limit {cap})")]
pub struct SideDataEntries {
count: i32,
cap: usize,
}
impl SideDataEntries {
/// Constructs a `SideDataEntries` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(count: i32, cap: usize) -> Self {
Self { count, cap }
}
/// The count the packet declared.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn count(&self) -> i32 {
self.count
}
/// The most entries this crate will walk.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn cap(&self) -> usize {
self.cap
}
}
/// Payload for [`PacketBufferError::SideDataArray`].
///
/// A packet declares side-data entries and carries no array to read
/// them from.
///
/// Malformed, and named rather than read as "no side data": a null
/// array with a positive count is the same silent loss as a truncated
/// copy, reached through the pointer instead of the cap.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("a packet declaring {count} side-data entries carries no array")]
pub struct SideDataArray {
count: i32,
}
impl SideDataArray {
/// Constructs a `SideDataArray` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(count: i32) -> Self {
Self { count }
}
/// The count the packet declared.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn count(&self) -> i32 {
self.count
}
}
/// Payload for [`PacketBufferError::SideDataPayload`].
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("side-data entry {index} declares {size} bytes and carries no data")]
pub struct SideDataPayload {
index: usize,
size: usize,
}
impl SideDataPayload {
/// Constructs a `SideDataPayload` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(index: usize, size: usize) -> Self {
Self { index, size }
}
/// The entry's position in the packet's array.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn index(&self) -> usize {
self.index
}
/// The length the entry declared.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn size(&self) -> usize {
self.size
}
}
/// Payload for [`PacketBufferError::SideDataBytes`].
///
/// A packet's side data is larger than this crate will copy.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("{bytes} bytes of side data cannot be carried (limit {cap})")]
pub struct SideDataBytes {
bytes: usize,
cap: usize,
}
impl SideDataBytes {
/// Constructs a `SideDataBytes` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(bytes: usize, cap: usize) -> Self {
Self { bytes, cap }
}
/// The total the packet's entries reached.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn bytes(&self) -> usize {
self.bytes
}
/// The most bytes this crate will copy.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn cap(&self) -> usize {
self.cap
}
}
/// Payload for [`PacketBufferError::UnrepresentableFlags`].
///
/// A packet carries flag bits the portable vocabulary cannot hold.
///
/// `mediadecode`'s `PacketFlags` is a `u8` bit set, and every packet
/// flag FFmpeg names today lives in that byte — so this cannot fire
/// against this build. It exists so that the day one does not, the
/// packet is refused by name instead of arriving with a bit quietly
/// missing: the same rule the rest of this boundary keeps.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("packet flags {raw:#x} do not fit the portable flag set")]
pub struct UnrepresentableFlags {
raw: i32,
}
impl UnrepresentableFlags {
/// Constructs an `UnrepresentableFlags` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(raw: i32) -> Self {
Self { raw }
}
/// `AVPacket.flags` as FFmpeg wrote it.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn raw(&self) -> i32 {
self.raw
}
}
/// Payload for [`PacketBufferError::SideDataAlloc`].
///
/// Out of memory copying a side-data entry.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("out of memory copying {size} bytes of side data")]
pub struct SideDataAlloc {
size: usize,
}
impl SideDataAlloc {
/// Constructs a `SideDataAlloc` payload.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn new(size: usize) -> Self {
Self { size }
}
/// The entry's length in bytes.
#[cfg_attr(not(tarpaulin), inline(always))]
pub const fn size(&self) -> usize {
self.size
}
}
/// Why a packet could not be carried across the boundary — its payload,
/// or the side data that comes with it.
///
/// Every arm means the bytes are real and this crate could not carry
/// them — never that there were none. "No payload" is `Ok(None)` from
/// [`payload_of`], and keeping the two apart is the whole point of the
/// type: a demuxer that reads a malformed packet as an empty marker
/// drops a video packet and carries on as though the file said so. The
/// side-data arms exist for the same reason one tier along — a packet
/// whose side data cannot be carried whole is refused, never delivered
/// with some of it.
#[derive(Copy, Clone, Debug, PartialEq, Eq, thiserror::Error, IsVariant, Unwrap, TryUnwrap)]
#[unwrap(ref, ref_mut)]
#[try_unwrap(ref, ref_mut)]
pub enum PacketBufferError {
/// The payload is larger than the budget in force. Refused before
/// the copy.
#[error(transparent)]
PacketTooLarge(#[from] PacketTooLarge),
/// The payload does not lie inside the packet's own buffer.
#[error(transparent)]
Bounds(#[from] Bounds),
/// A packet declares more side-data entries than this crate will
/// walk, or a negative count.
#[error(transparent)]
SideDataEntries(#[from] SideDataEntries),
/// A packet declares side-data entries and carries no array to read
/// them from.
#[error(transparent)]
SideDataArray(#[from] SideDataArray),
/// A side-data entry declares bytes it does not carry.
#[error(transparent)]
SideDataPayload(#[from] SideDataPayload),
/// A packet's side data is larger than this crate will copy.
#[error(transparent)]
SideDataBytes(#[from] SideDataBytes),
/// A packet carries flag bits the portable vocabulary cannot hold.
#[error(transparent)]
UnrepresentableFlags(#[from] UnrepresentableFlags),
/// A packet is marked `AV_PKT_FLAG_TRUSTED`, so its payload may hold
/// pointers rather than bytes. See [`TrustedPayload`].
#[error(transparent)]
TrustedPayload(#[from] TrustedPayload),
/// The capture itself failed — an allocation on the owned lane, a
/// refcount on the view lane. See [`CaptureFailed`].
#[error(transparent)]
CaptureFailed(#[from] CaptureFailed),
/// The payload's buffer is referenced by something other than the
/// packet it came from. See [`SharedPayload`].
#[error(transparent)]
SharedPayload(#[from] SharedPayload),
/// Out of memory copying a side-data entry.
#[error(transparent)]
SideDataAlloc(#[from] SideDataAlloc),
}
impl PacketBufferError {
/// Whether the demux session should **park** the packet this refusal
/// came from and re-attempt it on the next pull.
///
/// Deliberately not public, and deliberately named for the decision
/// rather than for a property of the error. It was briefly public as
/// `is_transient`, which promised more than an error enum can know:
/// whether retrying helps depends on *what was retried*.
/// `SharedPayload` is permanent for a caller who keeps their other
/// reference and retryable the moment they drop it;
/// `CaptureFailed` is worth another attempt only if the packet still
/// exists to attempt, which on a **consuming** conversion it does
/// not. Only the demux loop knows both halves — it still holds the
/// packet, and it knows nobody else does.
///
/// So this answers one question for one caller. An allocation that
/// failed says nothing about the packet, and the demux loop is
/// holding the bytes; everything else is a fact about the packet
/// itself, and parking it would answer every later pull with the same
/// error instead of letting the session make progress.
///
/// **The door left open:** a public retry signal would have to know
/// which operation produced the error and what the caller still
/// holds — an operation-aware answer, not a property of this enum.
/// If one is ever wanted it is designed then, not approximated now.
#[inline]
pub(crate) const fn parks_in_demux(&self) -> bool {
matches!(self, Self::CaptureFailed(_) | Self::SideDataAlloc(_))
}
}
/// `AV_PKT_FLAG_TRUSTED` as the bit the portable `PacketFlags` byte
/// carries it in.
///
/// The core vocabulary deliberately does not *name* this flag — it is
/// FFmpeg's, not a portable fact about packets — but `from_bits_retain`
/// keeps the bit, so this crate can recognise its own flag coming back
/// without the core growing a constant for it.
pub(crate) const TRUSTED_BIT: u8 = ffmpeg_next::ffi::AV_PKT_FLAG_TRUSTED as u8;
/// Compile-time proof that the flag really does fit the byte, so the
/// cast above cannot silently become a different bit.
const _: () = {
assert!(
ffmpeg_next::ffi::AV_PKT_FLAG_TRUSTED > 0
&& ffmpeg_next::ffi::AV_PKT_FLAG_TRUSTED <= u8::MAX as std::ffi::c_int,
"AV_PKT_FLAG_TRUSTED no longer fits the portable flag byte",
);
};
/// Payload for [`PacketBufferError::TrustedPayload`] and
/// [`crate::boundary::PacketBuildError::TrustedPayload`].
///
/// A packet carrying `AV_PKT_FLAG_TRUSTED`, refused on both legs.
///
/// # Why a flag makes a payload uncarriable
///
/// `AV_PKT_FLAG_TRUSTED` is FFmpeg's marker for a packet whose bytes
/// came from a source the *decoder* may treat as its own — and the
/// wrapped-AVFrame producers use it for exactly that: the payload is
/// not media, it is a **structure containing pointers to other live
/// objects** (an `AVFrame` and its buffers), passed by address between
/// components inside one FFmpeg pipeline.
///
/// This crate copies bytes. A pointer copied by value is not owned by
/// the copy — and that is not a gap this crate can close, because there
/// is no bound on what a payload's pointers might reach. So the
/// amputation has a corollary:
///
/// > **A payload that carries addresses instead of bytes cannot be
/// > carried.** Copying it produces a message that looks owned, is
/// > `Send + Sync + 'static` by every type-level test, and dangles the
/// > moment its source is dropped — a use-after-free reachable through
/// > entirely safe API.
///
/// Refusing is not conservatism, it is the only correct answer: the
/// contract this crate exists to keep says every byte leaving FFmpeg is
/// copied once into memory Rust owns, and a pointer cannot be.
///
/// Refused at **both** legs, because either one alone leaves the loop
/// open: copy-out ([`payload_of`]) is where such a packet would enter
/// the graph, and the reverse builders are where a flag that survived
/// some other route would be handed back to a decoder that trusts it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TrustedPayload {
len: usize,
}
impl TrustedPayload {
/// Constructs a `TrustedPayload` payload.
#[inline]
pub const fn new(len: usize) -> Self {
Self { len }
}
/// How many bytes the packet declared.
#[inline]
pub const fn len(&self) -> usize {
self.len
}
/// Whether the refused packet declared no bytes.
#[inline]
pub const fn is_empty(&self) -> bool {
self.len == 0
}
}
impl core::fmt::Display for TrustedPayload {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(
f,
"packet of {} bytes carries AV_PKT_FLAG_TRUSTED; a payload that may hold \
pointers to other objects cannot be copied into an owned carrier",
self.len,
)
}
}
impl std::error::Error for TrustedPayload {}
/// The payload of a raw `AVPacket`, copied out.
///
/// Shared by the four timed boundary conversions, the attachment
/// conversion, and the demuxer's capture of `AVStream.attached_pic` —
/// an `AVPacket` embedded in the stream by value, which no safe
/// wrapper reaches. One implementation, so the empty-versus-malformed
/// distinction cannot drift between them.
///
/// `Ok(None)` means the packet carries no payload at all: an empty
/// marker, which some demuxers emit. That is a fact about the packet
/// and is kept apart from [`PacketBufferError`], which is a failure to
/// take a payload that *is* there.
///
/// A packet whose `buf` is null — a stack- or arena-allocated
/// `AVPacket` — still reads as "no payload", exactly as it did before
/// the amputation. It is tempting now that the bytes are copied to
/// serve those from `data` / `size` directly, and that is precisely the
/// case with no owning buffer to bound the read against: the claim
/// would have to be taken on faith.
///
/// # Safety
///
/// `pkt` must be a live `*const AVPacket` for the duration of this
/// call.
pub(crate) unsafe fn payload_of<C: crate::FfmpegCarrier + crate::CarrierOps>(
pkt: *const ffmpeg_next::ffi::AVPacket,
budget: usize,
provenance: PayloadProvenance,
) -> Result<Option<C::Buffer>, PacketBufferError> {
// SAFETY: `pkt` is live per the contract above; `.buf`, `.data` and
// `.size` are public fields on `AVPacket`, and `buf` may be null
// (stack-allocated packets).
let buf_ptr = unsafe { (*pkt).buf };
let data_ptr = unsafe { (*pkt).data };
let size_raw = unsafe { (*pkt).size };
// **The uncarriable-payload refusal, ahead of everything.** See
// [`TrustedPayload`]: this flag marks a payload that may be a
// structure of pointers into other live objects rather than media
// bytes, and copying those bytes would mint an owned-looking carrier
// full of addresses that dangle as soon as the source is dropped.
//
// Judged before the empty-payload answer as well as before the copy:
// "there is nothing to take here" is the wrong reply to a packet this
// crate must not take *anything* from.
//
// SAFETY: `pkt` is live per the contract; `flags` is a public `c_int`
// field, read as the integer it is.
let flags_raw = unsafe { (*pkt).flags };
if flags_raw & ffmpeg_next::ffi::AV_PKT_FLAG_TRUSTED != 0 {
return Err(PacketBufferError::TrustedPayload(TrustedPayload::new(
size_raw.max(0) as usize,
)));
}
if buf_ptr.is_null() || data_ptr.is_null() || size_raw <= 0 {
return Ok(None);
}
let len = size_raw as usize;
// **The budget, before anything is read or allocated.** Judged on
// the declared length rather than on what the copy turns out to
// cost, because the point is to refuse without paying. Ahead of the
// bounds check too: a forged `size` is exactly what both exist for,
// and the cheaper judgement goes first.
if len > budget {
return Err(PacketBufferError::PacketTooLarge(PacketTooLarge::new(
len, budget,
)));
}
// SAFETY: `buf_ptr` is a live `AVBufferRef` owned by the packet.
let buf_data = unsafe { (*buf_ptr).data };
let size = unsafe { (*buf_ptr).size };
if buf_data.is_null() {
return Err(PacketBufferError::Bounds(Bounds::new(0, len, size)));
}
// `AVPacket` guarantees `data` lies within
// `buf->data .. buf->data + buf->size`. Checked before the copy, not
// instead of it: 0.8 formed a view over the claimed range and a
// malformed `size` handed out a slice nobody read; 0.9 reads every
// byte of it, so an unchecked claim is an out-of-bounds read rather
// than a latent one.
let offset = (data_ptr as usize).wrapping_sub(buf_data as usize);
match offset.checked_add(len) {
Some(end) if end <= size => {}
_ => {
return Err(PacketBufferError::Bounds(Bounds::new(offset, len, size)));
}
}
// **The sharing question, asked before any byte is read.**
//
// Everything below reads the payload — the view lane by handing out a
// span over it, the owned lane by copying it — so a buffer somebody
// else references has to be classified before it is touched. What
// matters is not the count but **who** the other holder is, and only
// the caller of this function knows that: see [`PayloadProvenance`]
// for the dichotomy and [`PayloadProvenance::route`] for the table.
//
// Placed here rather than inside the capture so the ordering is a
// property of this function rather than of two lane impls: nothing
// between the bounds proof and this decision touches the payload.
//
// SAFETY: `buf_ptr` is a live `AVBufferRef` owned by the packet;
// `av_buffer_get_ref_count` only reads its atomic.
let references = unsafe { ffmpeg_next::ffi::av_buffer_get_ref_count(buf_ptr.cast_const()) };
let route = provenance.route(references != 1);
if route == CaptureRoute::Refuse {
return Err(PacketBufferError::SharedPayload(SharedPayload::new(
references,
)));
}
// **The capture, and the only step the two lanes spell differently.**
// Everything above — the `TRUSTED` refusal, the empty answer, the
// budget, the extent proof — is shared, which is what keeps the view
// lane from having to re-earn a single one of them.
//
// The **packet-payload** capture, not the general one: this range is
// an `AVPacket`'s payload inside that packet's own buffer, which is
// the one place libavformat's trailing-padding contract applies. The
// view lane records that, and the send leg is the only thing that
// reads it back — see `boundary::share_or_copy`.
//
// SAFETY: `offset + len` was just proved to lie inside `buf_ptr`'s
// own `size`, and `buf_ptr` is a live `AVBufferRef` the packet owns.
let carried = match route {
CaptureRoute::Capture => unsafe { C::capture_packet_payload(buf_ptr, offset, len) },
CaptureRoute::Copy => {
// A demux-delivered packet whose buffer libavformat also holds.
// Reading it here is race-free — every other reference is
// C-owned, no `ffmpeg_next::Packet` wraps one, and this crate
// holds the `AVFormatContext` exclusively for the duration of
// the call — but the copy is what keeps that argument confined
// to *this* call instead of to the carrier's whole life.
//
// SAFETY: the extent was proved above and `buf_data` is
// non-null.
let bytes = unsafe { core::slice::from_raw_parts(buf_data.add(offset).cast_const(), len) };
C::from_bytes(bytes)
}
// Answered before the payload was touched.
CaptureRoute::Refuse => unreachable!("a refusal returns above"),
};
carried
.map(Some)
.ok_or(PacketBufferError::CaptureFailed(CaptureFailed::new(len)))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::limits::DEFAULT_MAX_PACKET_BYTES;
use ffmpeg_next::{Packet, packet::Ref};
#[test]
fn a_real_payload_is_copied_out_whole() {
let packet = Packet::copy(&[1u8, 2, 3, 4]);
// SAFETY: `packet` owns a live `AVPacket` for the call.
let payload = unsafe {
payload_of::<crate::Owned>(
packet.as_ptr(),
DEFAULT_MAX_PACKET_BYTES,
PayloadProvenance::CallerSupplied,
)
}
.expect("a well-formed packet is carriable")
.expect("present");
assert_eq!(payload.as_ref(), &[1, 2, 3, 4]);
}
#[test]
fn the_copy_outlives_the_packet_it_came_from() {
// The whole point of the amputation: FFmpeg's allocation is gone
// and the bytes are still here.
let packet = Packet::copy(&[9u8, 8, 7]);
// SAFETY: `packet` owns a live `AVPacket` for the call.
let payload = unsafe {
payload_of::<crate::Owned>(
packet.as_ptr(),
DEFAULT_MAX_PACKET_BYTES,
PayloadProvenance::CallerSupplied,
)
}
.expect("carriable")
.expect("present");
let shared = payload.clone();
assert!(shared.ptr_eq(&payload), "the clone copied the bytes");
drop(packet);
drop(payload);
assert_eq!(shared.as_ref(), &[9, 8, 7]);
}
#[test]
fn an_empty_packet_has_no_payload_rather_than_a_failure() {
let packet = Packet::empty();
// SAFETY: `packet` owns a live `AVPacket` for the call.
assert!(
unsafe {
payload_of::<crate::Owned>(
packet.as_ptr(),
DEFAULT_MAX_PACKET_BYTES,
PayloadProvenance::CallerSupplied,
)
}
.expect("not a failure")
.is_none()
);
}
#[test]
fn a_payload_outside_its_own_buffer_is_refused_before_a_byte_is_read() {
use ffmpeg_next::packet::Mut;
let mut packet = Packet::copy(&[1u8, 2, 3, 4]);
// SAFETY: `packet` owns a live `AVPacket`; `size` is a public
// field. The forged claim is the read this check exists to stop.
unsafe {
(*packet.as_mut_ptr()).size = 1 << 20;
}
// SAFETY: `packet` owns a live `AVPacket` for the call.
assert!(matches!(
unsafe {
payload_of::<crate::Owned>(
packet.as_ptr(),
DEFAULT_MAX_PACKET_BYTES,
PayloadProvenance::CallerSupplied,
)
},
Err(PacketBufferError::Bounds(_)),
));
}
#[test]
fn the_shared_empty_carrier_is_one_allocation() {
let a = FfmpegBytes::empty();
let b = FfmpegBytes::empty();
assert!(a.is_empty());
assert_eq!(a.len(), 0);
assert!(a.ptr_eq(&b), "the empty carrier is shared, not remade");
// And a zero-length copy lands on that same allocation rather than
// minting its own.
assert!(FfmpegBytes::copy_from_slice(&[]).ptr_eq(&a));
}
#[test]
fn copy_out_is_owned_and_shareable() {
fn owned_and_shareable<T: Send + Sync + Clone + 'static>(_: &T) {}
let carrier = FfmpegBytes::copy_from_slice(&[4u8, 5, 6]);
owned_and_shareable(&carrier);
assert_eq!(carrier.as_ref(), &[4, 5, 6]);
// Terse `Debug` — the bytes never reach a log line through it.
let rendered = format!("{carrier:?}");
assert!(rendered.contains("len: 3"), "got {rendered}");
assert!(!rendered.contains('4'), "got {rendered}");
}
}
/// Where the packet a payload is taken from came from — and therefore
/// what a second reference to its buffer can do.
///
/// The dichotomy is **delivered by libavformat** versus **handed over
/// by a caller**, and it is about who can *write*, not how many
/// references there are.
///
/// * A packet this crate's own read loop just took from
/// `av_read_frame` — or hoisted out of `AVStream.attached_pic` — may
/// well share its buffer, and every other reference to it is
/// libavformat's. FFmpeg writes through a buffer only after
/// `av_buffer_make_writable`, which *copies* when the buffer is
/// shared; and while this crate is reading, it holds the
/// `AVFormatContext` exclusively, so no libavformat code is running
/// at all. There is no safe-Rust `data_mut` on any of those
/// references, because no `ffmpeg_next::Packet` wraps them.
/// * A packet a **caller** hands over may share its buffer with
/// another `ffmpeg_next::Packet` — and that type's `data_mut` writes
/// in place from safe code, without consulting writability. That is
/// the writer the uniqueness rule exists for, and it may be on
/// another thread.
///
/// Spelled out as a parameter rather than assumed at the call sites,
/// because a blanket "refcount must be one" looked right and was twice
/// wrong: it refused every embedded cover picture, and then every
/// packet from a queue-backed subtitle demuxer, which delivers
/// `av_packet_ref`s of originals it keeps in its own queue.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum PayloadProvenance {
/// A packet a caller handed to a public conversion. A second
/// reference may be a `Packet` with a safe `data_mut`; shared is
/// refused by name.
CallerSupplied,
/// A packet this crate's demux loop just received from
/// `av_read_frame`. Secondary references are libavformat's own.
DemuxDelivered,
/// The container's parked picture, whether hoisted at open or queued
/// as a stream's first packet. Written once while the container was
/// opened and never again.
AttachedPicture,
}
/// How a payload of a given provenance may be captured once its extent
/// is proved.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum CaptureRoute {
/// The ordinary road: the view lane takes a window, the owned lane
/// copies.
Capture,
/// Both lanes copy. The bytes are safe to *read* — no safe-Rust
/// writer exists — but no long-lived window may be opened onto a
/// buffer somebody else also holds unless something stronger than
/// "nobody is writing right now" is true of it.
Copy,
/// Refuse without reading a byte.
Refuse,
}
impl PayloadProvenance {
/// What to do with a payload whose buffer has `shared` other
/// references.
///
/// | provenance | unique | shared | the argument |
/// |---|---|---|---|
/// | [`Self::CallerSupplied`] | capture | **refuse** | a second `Packet`'s `data_mut` writes in place from safe code, possibly on another thread |
/// | [`Self::DemuxDelivered`] | capture | **copy** | the read is race-free — every other reference is C-owned and the context is held exclusively — but a *window* would outlive that exclusivity, and FFmpeg's copy-on-write discipline is a weaker guarantee than this crate wants under a long-lived span |
/// | [`Self::AttachedPicture`] | capture | **capture** | `AVStream.attached_pic` is written once while the container opens and never again, so a window onto it is as stable as one onto a private buffer |
///
/// The middle row is the deliberate one. Sharing there would have
/// rested on "libavformat honours its own writability rules
/// forever"; copying rests on "nothing can be writing while we hold
/// the context", which is a fact about *this* call and needs no
/// promise about anyone's future behaviour. Subtitle queues — the
/// shape that produced this row — carry payloads measured in bytes,
/// so the copy is not a cost worth an argument.
#[inline]
pub(crate) const fn route(self, shared: bool) -> CaptureRoute {
match (self, shared) {
(_, false) | (Self::AttachedPicture, true) => CaptureRoute::Capture,
(Self::DemuxDelivered, true) => CaptureRoute::Copy,
(Self::CallerSupplied, true) => CaptureRoute::Refuse,
}
}
}
/// A packet whose payload buffer somebody else still references.
///
/// **Refused without reading a byte of it, and that is the whole
/// point.** A refcount above one is exactly the state in which another
/// handle to the same allocation may exist — `ffmpeg_next::Packet`
/// hands out `&mut [u8]` through `data_mut` from entirely safe code,
/// and a `Packet` is `Send`, so that handle may be on another thread
/// writing right now. Forming a `&[u8]` over those bytes is a data race
/// whether the bytes are then viewed *or copied*: the copy needs the
/// read, and the read is the race.
///
/// An earlier round answered this shape with a silent copy, reasoning
/// that a copy is always sound and keeps the API total. That was wrong
/// in the direction that matters — it traded soundness for totality.
/// The refcount protects the allocation's *lifetime*; it says nothing
/// about who may be writing into it.
///
/// The ordinary roads never see this: a packet from `av_read_frame` is
/// uniquely referenced, and so is one the caller cloned successfully.
/// What produces it is a second reference the caller may not know they
/// have — see `ffmpeg_next::Packet::clone`, which ignores
/// `av_packet_make_writable`'s return code.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error(
"packet payload buffer is shared ({references} references): its bytes cannot be read \
without racing whoever else holds it"
)]
pub struct SharedPayload {
references: i32,
}
impl SharedPayload {
/// Constructs a `SharedPayload` payload.
#[inline]
#[must_use]
pub const fn new(references: i32) -> Self {
Self { references }
}
/// References the payload's buffer had when it was refused.
#[inline]
#[must_use]
pub const fn references(&self) -> i32 {
self.references
}
}
/// Payload for [`PacketBufferError::CaptureFailed`].
///
/// The proofs all passed and the carrier still could not be formed:
/// `av_buffer_alloc` returned null on the owned lane, or
/// `av_buffer_ref` did on the view lane. Distinct from
/// [`Bounds`] on purpose — a malformed packet and an exhausted
/// allocator are different facts, and 0.8 reported both as an absent
/// payload.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("could not capture a {len}-byte payload: the allocator or the refcount refused")]
pub struct CaptureFailed {
len: usize,
}
impl CaptureFailed {
/// Constructs a `CaptureFailed` payload.
#[inline]
pub const fn new(len: usize) -> Self {
Self { len }
}
/// Bytes the capture was for.
#[inline]
pub const fn len(&self) -> usize {
self.len
}
/// Whether the refused capture was of no bytes.
#[inline]
pub const fn is_empty(&self) -> bool {
self.len == 0
}
}