reactor-effect-native 0.2.0 → 0.3.0-rc.0

package/rust/build.rs

@@ -1,85 +1,207 @@
+//! Embeds the library's source and build identity and, on macOS, links the
+//! compiler-rt archive that the pinned libwebrtc needs.
+//!
+//! The identity is a JSON object that `scripts/stage.mjs` finds in the built
+//! library and checks against the checked-out sources before staging it. Its
+//! `sourceSha256` covers the same files, hashed the same way, as
+//! `stage.mjs --source-hash` and the pack check in `scripts/pack.ts`. Its
+//! `webrtcPrebuilt` names the Reactor libwebrtc prebuilt that
+//! `reactor-webrtc-sys` links, which staging checks against the shipped SBOM.
+
 use std::env;
+use std::error::Error;
+use std::fmt::{self, Write as _};
 use std::fs;
-use std::io::Write;
+use std::io::{self, Write as _};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 
-fn source_files(root: &Path, directory: &Path, files: &mut Vec<String>) {
-    for entry in fs::read_dir(directory).expect("native source directory must exist") {
-        let path = entry.expect("read native source entry").path();
-        if path.is_dir() {
-            source_files(root, &path, files);
-        } else if path.is_file() {
-            files.push(
-                path.strip_prefix(root)
-                    .unwrap()
-                    .to_str()
-                    .unwrap()
-                    .replace('\\', "/"),
-            );
-        }
+/// A failed build step, which Cargo reports with the script's output.
+type BuildResult<T> = Result<T, Box<dyn Error>>;
+
+/// The C ABI version. A library test checks it against `abi::ABI_VERSION`.
+const ABI_VERSION: u32 = 4;
+
+/// The source identity's inputs outside `src/`, which it covers entirely.
+const SOURCE_FILES: [&str; 5] = [
+    "Cargo.toml",
+    "Cargo.lock",
+    "build.rs",
+    ".cargo/config.toml",
+    "include/reactor_effect_native.h",
+];
+
+/// Overrides that make `reactor-webrtc-sys` link something other than its
+/// tagged prebuilt; with either set, the identity names no prebuilt.
+const WEBRTC_OVERRIDES: [&str; 2] = ["REACTOR_WEBRTC_LIB_DIR", "REACTOR_WEBRTC_PREBUILT_URL"];
+
+/// Environment that changes the compiled library, recorded when set.
+const BUILD_ENVIRONMENT: [&str; 6] = [
+    "CC",
+    "CXX",
+    "CARGO_ENCODED_RUSTFLAGS",
+    "CFLAGS",
+    "CXXFLAGS",
+    "MACOSX_DEPLOYMENT_TARGET",
+];
+
+fn main() -> BuildResult<()> {
+    let root = env::var_os("CARGO_MANIFEST_DIR")
+        .map(PathBuf::from)
+        .ok_or("Cargo sets CARGO_MANIFEST_DIR")?;
+    let identity = build_identity(&root)?;
+    println!("cargo::rustc-env=REACTOR_EFFECT_BUILD_IDENTITY={identity}");
+    if env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("macos") {
+        link_compiler_rt()?;
     }
+    Ok(())
 }
 
-fn quote(value: &str) -> String {
-    let mut out = String::from("\"");
-    for ch in value.chars() {
-        match ch {
-            '"' => out.push_str("\\\""),
-            '\\' => out.push_str("\\\\"),
-            '\n' => out.push_str("\\n"),
-            '\r' => out.push_str("\\r"),
-            '\t' => out.push_str("\\t"),
-            ch if ch.is_control() => out.push_str(&format!("\\u{:04x}", ch as u32)),
-            ch => out.push(ch),
+/// The identity JSON: the source hash, target and profile, the toolchain's
+/// versions and the build environment.
+fn build_identity(root: &Path) -> BuildResult<String> {
+    let cc = env::var("CC").unwrap_or_else(|_| "clang".to_owned());
+    let cxx = env::var("CXX").unwrap_or_else(|_| "clang++".to_owned());
+    let rustc = cargo_env("RUSTC")?;
+    // Each value is already JSON.
+    let mut fields = vec![
+        ("schemaVersion", "1".to_owned()),
+        ("abiVersion", ABI_VERSION.to_string()),
+        ("sourceSha256", json_string(&source_sha256(root)?)),
+        ("target", json_string(&cargo_env("TARGET")?)),
+        ("profile", json_string(&cargo_env("PROFILE")?)),
+        ("rustc", json_string(&tool_version(&rustc)?)),
+        ("cc", json_string(&tool_version(&cc)?)),
+        ("cxx", json_string(&tool_version(&cxx)?)),
+        (
+            "webrtcPrebuilt",
+            webrtc_prebuilt(root)?.map_or_else(|| "null".to_owned(), |tag| json_string(&tag)),
+        ),
+    ];
+    for key in BUILD_ENVIRONMENT {
+        println!("cargo::rerun-if-env-changed={key}");
+        if let Ok(value) = env::var(key) {
+            fields.push((key, json_string(&value)));
         }
     }
-    out.push('"');
-    out
+    let fields: Vec<String> = fields
+        .iter()
+        .map(|(key, value)| format!("{}:{value}", json_string(key)))
+        .collect();
+    Ok(format!("{{{}}}", fields.join(",")))
 }
 
-fn version(program: &str) -> String {
-    let output = Command::new(program)
-        .arg("--version")
+/// The prebuilt tag `reactor-webrtc-sys` downloads, derived as it derives it:
+/// from `WEBRTC_VERSION` at the root of the pinned `reactor-webrtc` checkout.
+/// `None` when an override links a local or custom archive instead.
+fn webrtc_prebuilt(root: &Path) -> BuildResult<Option<String>> {
+    for key in WEBRTC_OVERRIDES {
+        println!("cargo::rerun-if-env-changed={key}");
+        if env::var_os(key).is_some() {
+            return Ok(None);
+        }
+    }
+    let output = Command::new(cargo_env("CARGO")?)
+        .args(["metadata", "--format-version", "1", "--offline", "--locked"])
+        .arg("--manifest-path")
+        .arg(root.join("Cargo.toml"))
         .output()
-        .unwrap_or_else(|_| panic!("could not inspect native build tool {program}"));
-    assert!(
-        output.status.success(),
-        "native build tool {program} failed"
-    );
-    String::from_utf8(output.stdout)
-        .expect("build tool version must be UTF-8")
-        .lines()
-        .next()
-        .unwrap_or("")
-        .to_owned()
+        .map_err(|error| format!("cargo metadata could not run: {error}"))?;
+    if !output.status.success() {
+        return Err(format!("cargo metadata failed: {}", output.status).into());
+    }
+    let metadata = String::from_utf8(output.stdout)?;
+    let manifest = metadata
+        .split("\"manifest_path\":\"")
+        .skip(1)
+        .filter_map(|rest| rest.split('"').next())
+        .find(|path| path.ends_with("/reactor-webrtc-sys/Cargo.toml"))
+        .ok_or("cargo metadata names no reactor-webrtc-sys manifest")?;
+    // `<checkout>/crates/reactor-webrtc-sys/Cargo.toml`, as its build script reads it.
+    let version = Path::new(manifest)
+        .ancestors()
+        .nth(3)
+        .ok_or("reactor-webrtc-sys is not inside a reactor-webrtc checkout")?
+        .join("WEBRTC_VERSION");
+    println!("cargo::rerun-if-changed={}", version.display());
+    let source = fs::read_to_string(&version)
+        .map_err(|error| format!("read {}: {error}", version.display()))?;
+    prebuilt_tag(&source).map(Some)
 }
 
-fn build_identity() {
-    let root = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
-    let mut files = [
-        "Cargo.toml",
-        "Cargo.lock",
-        "build.rs",
-        ".cargo/config.toml",
-        "include/reactor_effect_native.h",
-    ]
-    .map(str::to_owned)
-    .to_vec();
-    source_files(&root, &root.join("src"), &mut files);
+/// `webrtc-<milestone>-<commit8>-p<patch>` from `WEBRTC_VERSION`'s variables.
+fn prebuilt_tag(source: &str) -> BuildResult<String> {
+    let (mut branch, mut commit, mut patch) = (None, None, "0");
+    for line in source.lines().map(str::trim) {
+        if line.starts_with('#') {
+            continue;
+        }
+        if let Some(value) = line.strip_prefix("WEBRTC_BRANCH=") {
+            branch = Some(value);
+        } else if let Some(value) = line.strip_prefix("WEBRTC_COMMIT=") {
+            commit = Some(value);
+        } else if let Some(value) = line.strip_prefix("REACTOR_PATCH_LEVEL=") {
+            patch = value;
+        }
+    }
+    let branch = branch.ok_or("WEBRTC_VERSION names no WEBRTC_BRANCH")?;
+    let commit = commit
+        .and_then(|commit| commit.get(..8))
+        .ok_or("WEBRTC_VERSION pins no WEBRTC_COMMIT")?;
+    let milestone = branch.strip_prefix("branch-heads/").unwrap_or(branch);
+    Ok(format!("webrtc-{milestone}-{commit}-p{patch}"))
+}
+
+/// A variable Cargo sets for every build script.
+fn cargo_env(key: &str) -> BuildResult<String> {
+    env::var(key).map_err(|error| format!("Cargo sets {key}: {error}").into())
+}
+
+/// SHA-256 over each source input, as `path NUL contents NUL` in path order.
+fn source_sha256(root: &Path) -> BuildResult<String> {
+    let mut files = SOURCE_FILES.map(str::to_owned).to_vec();
+    files.extend(files_under(root, &root.join("src"))?);
     files.sort();
+    // The directory as well, so a new source file reruns this script.
+    println!("cargo::rerun-if-changed=src");
     let mut input = Vec::new();
     for file in files {
-        println!("cargo:rerun-if-changed={file}");
+        println!("cargo::rerun-if-changed={file}");
+        let contents = fs::read(root.join(&file))
+            .map_err(|error| format!("read native build input {file}: {error}"))?;
         input.extend_from_slice(file.as_bytes());
         input.push(0);
-        input.extend_from_slice(&fs::read(root.join(file)).expect("read native build input"));
+        input.extend_from_slice(&contents);
         input.push(0);
     }
+    sha256_hex(&input)
+}
+
+/// Every file under `directory`, as a `/`-separated path relative to `root`.
+fn files_under(root: &Path, directory: &Path) -> BuildResult<Vec<String>> {
+    let unreadable = |error: io::Error| format!("read {}: {error}", directory.display());
+    let mut files = Vec::new();
+    for entry in fs::read_dir(directory).map_err(unreadable)? {
+        let path = entry.map_err(unreadable)?.path();
+        if path.is_dir() {
+            files.extend(files_under(root, &path)?);
+        } else if path.is_file() {
+            let relative = path
+                .strip_prefix(root)?
+                .to_str()
+                .ok_or_else(|| format!("source path is not UTF-8: {}", path.display()))?;
+            files.push(relative.replace('\\', "/"));
+        }
+    }
+    Ok(files)
+}
+
+/// SHA-256 as hex, from the platform's tool rather than a build dependency.
+fn sha256_hex(input: &[u8]) -> BuildResult<String> {
     let mut command = if cfg!(target_os = "macos") {
-        let mut command = Command::new("shasum");
-        command.args(["-a", "256"]);
-        command
+        let mut shasum = Command::new("shasum");
+        shasum.args(["-a", "256"]);
+        shasum
     } else {
         Command::new("sha256sum")
     };
@@ -87,73 +209,90 @@ fn build_identity() {
         .stdin(Stdio::piped())
         .stdout(Stdio::piped())
         .spawn()
-        .expect("a SHA-256 tool is required to identify native build inputs");
+        .map_err(|error| {
+            format!("a SHA-256 tool is required to identify native build inputs: {error}")
+        })?;
+    // The piped stdin closes at the end of this statement, ending the input.
     child
         .stdin
         .take()
-        .unwrap()
-        .write_all(&input)
-        .expect("hash native build inputs");
-    let output = child.wait_with_output().expect("join native source hash");
-    assert!(output.status.success(), "native source hash failed");
-    let text = String::from_utf8(output.stdout).unwrap();
-    let digest = text.split_whitespace().next().unwrap();
-    assert!(digest.len() == 64 && digest.chars().all(|ch| ch.is_ascii_hexdigit()));
-
-    let cc = env::var("CC").unwrap_or_else(|_| "clang".into());
-    let cxx = env::var("CXX").unwrap_or_else(|_| "clang++".into());
-    let mut fields = vec![
-        "\"schemaVersion\":1".to_owned(),
-        "\"abiVersion\":2".to_owned(),
-        format!("\"sourceSha256\":{}", quote(digest)),
-        format!("\"target\":{}", quote(&env::var("TARGET").unwrap())),
-        format!("\"profile\":{}", quote(&env::var("PROFILE").unwrap())),
-        format!("\"rustc\":{}", quote(&version(&env::var("RUSTC").unwrap()))),
-        format!("\"cc\":{}", quote(&version(&cc))),
-        format!("\"cxx\":{}", quote(&version(&cxx))),
-    ];
-    for key in [
-        "CC",
-        "CXX",
-        "CARGO_ENCODED_RUSTFLAGS",
-        "CFLAGS",
-        "CXXFLAGS",
-        "MACOSX_DEPLOYMENT_TARGET",
-    ] {
-        println!("cargo:rerun-if-env-changed={key}");
-        if let Ok(value) = env::var(key) {
-            fields.push(format!("{}:{}", quote(key), quote(&value)));
-        }
+        .ok_or("the hash tool has no stdin")?
+        .write_all(input)?;
+    let output = child.wait_with_output()?;
+    if !output.status.success() {
+        return Err(format!("native source hash failed: {}", output.status).into());
+    }
+    let text = String::from_utf8(output.stdout)?;
+    let digest = text.split_whitespace().next().unwrap_or_default();
+    if digest.len() != 64 || !digest.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return Err(format!("unexpected SHA-256 digest {digest:?}").into());
     }
-    println!(
-        "cargo:rustc-env=REACTOR_EFFECT_BUILD_IDENTITY={{{}}}",
-        fields.join(",")
-    );
+    Ok(digest.to_owned())
 }
 
-fn main() {
-    build_identity();
-    if env::var("CARGO_CFG_TARGET_OS").as_deref() != Ok("macos") {
-        return;
+/// The first line of `program --version`.
+fn tool_version(program: &str) -> BuildResult<String> {
+    let output = Command::new(program)
+        .arg("--version")
+        .output()
+        .map_err(|error| format!("could not inspect native build tool {program}: {error}"))?;
+    if !output.status.success() {
+        return Err(format!("native build tool {program} failed: {}", output.status).into());
+    }
+    let text = String::from_utf8(output.stdout)?;
+    Ok(text.lines().next().unwrap_or_default().to_owned())
+}
+
+/// `value` as a JSON string literal.
+fn json_string(value: &str) -> String {
+    JsonString(value).to_string()
+}
+
+/// Formats a string as a JSON string literal.
+struct JsonString<'a>(&'a str);
+
+impl fmt::Display for JsonString<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_char('"')?;
+        for ch in self.0.chars() {
+            match ch {
+                '"' => f.write_str("\\\"")?,
+                '\\' => f.write_str("\\\\")?,
+                '\n' => f.write_str("\\n")?,
+                '\r' => f.write_str("\\r")?,
+                '\t' => f.write_str("\\t")?,
+                ch if ch.is_control() => write!(f, "\\u{:04x}", u32::from(ch))?,
+                ch => f.write_char(ch)?,
+            }
+        }
+        f.write_char('"')
     }
+}
 
-    // The pinned Reactor libwebrtc archive contains ScreenCaptureKit objects
-    // produced by Clang. They reference compiler-rt's deployment-version helper,
-    // which rustc's macOS link line does not add on its own.
+/// The pinned Reactor libwebrtc archive contains `ScreenCaptureKit` objects
+/// produced by Clang. They reference compiler-rt's deployment-version helper,
+/// which rustc's macOS link line does not add on its own.
+fn link_compiler_rt() -> BuildResult<()> {
     let cc = env::var("CC").unwrap_or_else(|_| "clang".to_owned());
     let output = Command::new(cc)
         .arg("-print-resource-dir")
         .output()
-        .expect("clang is required to link the Reactor libwebrtc archive on macOS");
-    assert!(output.status.success(), "clang -print-resource-dir failed");
-    let resource = String::from_utf8(output.stdout).expect("clang resource path is not UTF-8");
+        .map_err(|error| {
+            format!("clang is required to link the Reactor libwebrtc archive on macOS: {error}")
+        })?;
+    if !output.status.success() {
+        return Err(format!("clang -print-resource-dir failed: {}", output.status).into());
+    }
+    let resource = String::from_utf8(output.stdout)?;
     let directory = PathBuf::from(resource.trim()).join("lib/darwin");
     let runtime = directory.join("libclang_rt.osx.a");
-    assert!(
-        runtime.is_file(),
-        "missing macOS compiler-rt archive at {}",
-        runtime.display()
-    );
-    println!("cargo:rustc-link-search=native={}", directory.display());
-    println!("cargo:rustc-link-lib=static=clang_rt.osx");
+    if !runtime.is_file() {
+        return Err(format!("missing macOS compiler-rt archive at {}", runtime.display()).into());
+    }
+    println!("cargo::rustc-link-search=native={}", directory.display());
+    println!("cargo::rustc-link-lib=static=clang_rt.osx");
+    // Cargo passes rustc-link-lib only to the library target, and the far-peer
+    // example cannot link this cdylib, so it names the archive itself.
+    println!("cargo::rustc-link-arg-examples={}", runtime.display());
+    Ok(())
 }

package/rust/clippy.toml

@@ -0,0 +1,7 @@
+# Lint levels live in Cargo.toml's [lints] table; this file only configures them.
+
+# In a test, a failed unwrap, expect, index or panic is the assertion.
+allow-unwrap-in-tests = true
+allow-expect-in-tests = true
+allow-indexing-slicing-in-tests = true
+allow-panic-in-tests = true

package/rust/include/reactor_effect_native.h

@@ -8,16 +8,30 @@
 extern "C" {
 #endif
 
+/* ABI 4. Every supported host is little-endian; headers are native-endian. */
+
 typedef struct ReactorEffectPeer ReactorEffectPeer;
 
+/*
+ * Non-negative statuses are outcomes. Negative statuses are failure classes;
+ * the set is closed for this ABI, and a host maps each class to its own error
+ * type. Diagnostic text travels beside a class in ReactorEffectFailure.
+ *
+ * A misaligned pointer argument fails with INVALID_INPUT without being used.
+ * A request over 1 MiB or a message over 256 KiB fails with OVERFLOW without
+ * being read.
+ */
 enum ReactorEffectStatus {
   REACTOR_EFFECT_OK = 0,
-  REACTOR_EFFECT_AGAIN = 1,
-  REACTOR_EFFECT_BUFFER_TOO_SMALL = 2,
-  REACTOR_EFFECT_CLOSED = 3,
-  REACTOR_EFFECT_INVALID = -1,
-  REACTOR_EFFECT_NATIVE = -2,
-  REACTOR_EFFECT_OVERFLOW = -3
+  REACTOR_EFFECT_AGAIN = 1,            /* take: the queue is empty */
+  REACTOR_EFFECT_BUFFER_TOO_SMALL = 2, /* sizes written; the item stays queued */
+  REACTOR_EFFECT_CLOSED = 3,           /* the peer is fenced or shut down */
+  REACTOR_EFFECT_INVALID_INPUT = -1,   /* an argument or request was rejected */
+  REACTOR_EFFECT_NATIVE = -2,          /* an unclassified libwebrtc or bridge failure */
+  REACTOR_EFFECT_OVERFLOW = -3,        /* a queue, buffer or message bound was exceeded */
+  REACTOR_EFFECT_PROTOCOL = -4,        /* the remote peer broke the negotiated contract */
+  REACTOR_EFFECT_SDP_REJECTED = -5,    /* libwebrtc refused to create or apply an SDP */
+  REACTOR_EFFECT_CHANNEL_CLOSED = -6   /* the data channel is not open */
 };
 
 enum ReactorEffectCall {
@@ -34,15 +48,63 @@ enum ReactorEffectChannel {
   REACTOR_EFFECT_DATA = 1
 };
 
+/* Readiness bits passed to ReactorEffectNotify. */
+enum ReactorEffectReady {
+  REACTOR_EFFECT_READY_EVENTS = 1,
+  REACTOR_EFFECT_READY_VIDEO = 2,
+  REACTOR_EFFECT_READY_AUDIO = 4
+};
+
+/* Diagnostic text for a failure status. Never match on it: the status is the class. */
+typedef struct ReactorEffectFailure {
+  uint32_t message_len;
+  uint8_t message[1020]; /* UTF-8, truncated on a character boundary */
+} ReactorEffectFailure;
+
+typedef struct ReactorEffectVideoHeader {
+  uint32_t width;
+  uint32_t height;
+  uint32_t data_len;     /* BGRA bytes: width * height * 4 */
+  uint32_t metadata_len; /* frame-metadata user data bytes */
+  uint64_t frame_id;     /* 0 when the sender supplied none */
+  uint64_t timestamp_us; /* sender capture time; 0 when absent */
+  uint32_t track;        /* index into the prepare request's tracks */
+  uint32_t reserved;
+  uint64_t sequence;     /* per-track admission sequence from 0, stamped before any queue drop */
+} ReactorEffectVideoHeader; /* 48 bytes */
+
+typedef struct ReactorEffectAudioHeader {
+  uint32_t sample_rate;
+  uint32_t channels;
+  uint32_t samples; /* interleaved int16_t samples: frames * channels */
+  uint32_t track;   /* index into the prepare request's tracks */
+  uint64_t sequence; /* per-track admission sequence from 0, stamped before any queue drop */
+} ReactorEffectAudioHeader; /* 24 bytes */
+
+/*
+ * Runs on the peer's notifier thread with the readiness bits of every queue
+ * that received an item since the previous call; a host must drain each named
+ * queue until AGAIN. The callback may call the take functions. libwebrtc
+ * threads never run it and never wait for it: while it has not returned, they
+ * keep queueing and the bounded queues count what they evict.
+ */
+typedef void (*ReactorEffectNotify)(uint32_t ready);
+
 uint32_t reactor_effect_abi_version(void);
 /* Static source/build identity of this loaded image; never free the pointer. */
 const char *reactor_effect_build_identity(void);
 
-ReactorEffectPeer *reactor_effect_peer_create(void);
+/*
+ * notify may be NULL: no notifier thread runs and the host polls the take
+ * functions itself. Every peer shares one process-wide libwebrtc factory,
+ * created on the first prepare and never destroyed.
+ */
+ReactorEffectPeer *reactor_effect_peer_create(ReactorEffectNotify notify);
 
 /*
- * request is UTF-8. The response is UTF-8 JSON on both success and failure.
- * Calls are serialized by the native peer owner and may block on libwebrtc.
+ * request is UTF-8. On OK the response is UTF-8 JSON and response_cap must be
+ * at least 4 MiB (BUFFER_TOO_SMALL reports that size). Calls are serialized by
+ * the native peer owner and may block on libwebrtc. failure may be NULL.
  */
 int reactor_effect_peer_call(
     ReactorEffectPeer *peer,
@@ -51,63 +113,60 @@ int reactor_effect_peer_call(
     size_t request_len,
     uint8_t *response,
     size_t response_cap,
-    size_t *response_len);
+    size_t *response_len,
+    ReactorEffectFailure *failure);
 
 int reactor_effect_peer_send(
     ReactorEffectPeer *peer,
     uint32_t channel,
     const uint8_t *data,
     size_t data_len,
-    uint8_t *error,
-    size_t error_cap,
-    size_t *error_len);
+    ReactorEffectFailure *failure);
 
 /*
- * Poll packets are [u32 little-endian header length][UTF-8 JSON header][payload].
- * A zero-capacity call returns BUFFER_TOO_SMALL with the required packet size and
- * retains that exact packet until copy or close. Retained packets count toward
- * item and byte bounds and cannot be evicted by producer pressure. Each queue
- * permits one reader across probe/copy; the host must serialize that pair.
- * timeout_ms == 0 is a nonblocking poll.
+ * Nonblocking takes. Each copies its queue's oldest item into caller memory
+ * once and removes it. BUFFER_TOO_SMALL writes the required size (out_len or
+ * the header) and keeps the item at the front; AGAIN means the queue is empty.
+ * Events are [u32 little-endian header length][UTF-8 JSON header][payload].
  */
-int reactor_effect_peer_poll_event(
+int reactor_effect_peer_take_event(
     ReactorEffectPeer *peer,
-    uint32_t timeout_ms,
     uint8_t *out,
     size_t out_cap,
     size_t *out_len);
 
-int reactor_effect_peer_poll_video(
+int reactor_effect_peer_take_video(
     ReactorEffectPeer *peer,
-    uint32_t timeout_ms,
-    uint8_t *out,
-    size_t out_cap,
-    size_t *out_len);
-
-int reactor_effect_peer_poll_audio(
+    ReactorEffectVideoHeader *header,
+    uint8_t *bgra,
+    size_t bgra_cap,
+    uint8_t *metadata,
+    size_t metadata_cap);
+
+/* pcm_cap counts int16_t samples, not bytes. */
+int reactor_effect_peer_take_audio(
     ReactorEffectPeer *peer,
-    uint32_t timeout_ms,
-    uint8_t *out,
-    size_t out_cap,
-    size_t *out_len);
+    ReactorEffectAudioHeader *header,
+    int16_t *pcm,
+    size_t pcm_cap);
 
 /* Immediate admission fence. No callback/event can be admitted after return. */
 void reactor_effect_peer_close(ReactorEffectPeer *peer);
 
 /*
- * Drops channels/tracks/PeerConnection on the owner thread, waits for all native
- * callback guards to leave, then joins that owner. Safe to call more than once.
+ * Drops channels/tracks/PeerConnection on the owner thread, waits for all
+ * native callback guards to leave, then joins that owner and the notifier
+ * thread. The notifier may be waiting for the host to run ReactorEffectNotify,
+ * so never call this from the thread that runs that callback. Safe to call
+ * more than once. failure may be NULL.
  */
-int reactor_effect_peer_shutdown(
-    ReactorEffectPeer *peer,
-    uint8_t *error,
-    size_t error_cap,
-    size_t *error_len);
+int reactor_effect_peer_shutdown(ReactorEffectPeer *peer, ReactorEffectFailure *failure);
 
 /*
- * Performs shutdown if needed, then frees the opaque handle. The host must
- * first join EVERY foreign call using this handle, including work still queued
- * in its FFI executor. Native owner shutdown alone does not establish that.
+ * Performs shutdown if needed (so the same thread rule applies), then frees
+ * the opaque handle. The host must first join EVERY foreign call using this
+ * handle, including work still queued in its FFI executor. Native owner
+ * shutdown alone does not establish that.
  */
 void reactor_effect_peer_destroy(ReactorEffectPeer *peer);