livekit-datatrack: stop aborting when a foreign E2EE provider errors (#1429)

## Problem

`EncryptionError` and `DecryptionError` are the error types of
`EncryptionProvider` and `DecryptionProvider`, both
`#[uniffi::export(with_foreign)]`. Foreign code implements those traits
-- `DataTrackCryptor` in the Android and Swift SDKs bridges data track
frames onto each platform's AES-GCM path -- so uniffi has to lift these
errors *into* Rust.

Both were `uniffi(flat_error)`. A flat error can be lowered but not
lifted: uniffi emits a `Lift` impl that exists only to satisfy trait
bounds and panics if called.

fn try_read(buf: &mut &[u8]) -> Result<Self> { panic!("Can't lift flat
errors") }

A panic in an FFI callback has nowhere to unwind to, so every failed
decrypt aborted the host process:

Fatal signal 6 (SIGABRT), code -1 (SI_QUEUE) in tid 31589 (Thread-24)
    Abort message: 'Can't lift flat errors'

That reached anything that can fail a decrypt: a subscriber with no E2EE
manager, a key mismatch, or a single corrupt frame. Reproduced on
Android against a real SFU; iOS ships the same cryptor and [the same
exposure](https://github.com/livekit/client-sdk-swift/blob/caf6a7b4f8cd9955b8257882bae9eb118705a3bd/Sources/LiveKit/E2EE/DataTrackE2EE.swift#L55).
Present since these types were introduced in #1034 -- data tracks had
simply never run a failed decrypt across the boundary.

## Fix

Drop `flat_error` from both enums and carry the detail in the variant:

    #[error("Decryption failed: {reason}")]
    Failed { reason: String },

This is the shape `PacketDeliveryError` already uses for the same
reason; it is the only other error returned across a `with_foreign`
trait. Both enums also gain its `From<UnexpectedUniFFICallbackError>`
catch-all, so a foreign provider throwing something other than the
declared type surfaces as an error rather than aborting.

`reason` is free-form host context (logged, not parsed), and it is the
first time the string a foreign cryptor builds reaches Rust at all:
under `flat_error` that message was write-only, since lowering
synthesized it from `Display` and lifting never happened.

The four construction sites in `livekit/src/room/e2ee/data_track.rs`
were all `map_err(|_| ..)`. Now that there is somewhere to put the
cause, they propagate it.

## Breaking Changes
* `EncryptionError::Failed` and `DecryptionError::Failed` are struct
variants.
* Rust callers construct `Failed { reason }`.
* Foreign callers still pass a single string:
  * Kotlin's positional `Failed(msg)` is source-compatible
  * Swift's `Failed(message:)` becomes `Failed(reason:)`

## Test

`cargo test -p livekit-datatrack --features uniffi`: 109 passed.

Regenerated the Kotlin and Swift bindings from the built cdylib. The
converter now reads the field instead of a synthesized `Display` string,
i.e. the real `Lift` impl replaced the panicking stub:

    1 -> DecryptionException.Failed(FfiConverterString.read(buf))

Built the Android AAR locally and re-ran the two e2e tests that
previously aborted (Pixel 6, real SFU): both pass, `logcat -b crash`
clean. A failed decrypt now logs and drops the frame, leaving the room
connected and the track published.

Author: davidliu

.changeset/liftable_e2ee_provider_errors.md

@@ -0,0 +1,12 @@
+---
+livekit-datatrack: minor
+livekit-uniffi: minor
+livekit: patch
+livekit-ffi: patch
+livekit-capture: patch
+---
+
+`EncryptionError::Failed` and `DecryptionError::Failed` carry a `reason` string and are no longer `flat_error`,
+so a foreign `EncryptionProvider` or `DecryptionProvider` returning an error no longer aborts the process with
+"Can't lift flat errors" -- a failed data track decrypt (no E2EE manager, key mismatch, corrupt frame) now 
+drops the frame and leaves the room connected.

AGENTS.md

@@ -88,6 +88,10 @@ Several crates export items to Swift/Kotlin/Node/Python through UniFFI — `live
   - Name the field `reason` in Rust instead — see `DataStreamError` in `livekit-uniffi/src/data_stream/common.rs`
 - A new crate that exports UniFFI items needs its own `uniffi.toml`, including `omit_checksums = true` under `[bindings.kotlin]`
   - The Kotlin checksum test is broken on ARM in every UniFFI release this workspace can use; the full explanation lives in `livekit-uniffi/uniffi.toml` and the root `Cargo.toml`
+- **Never use `uniffi(flat_error)` on an error that foreign code can return**
+  - Flat errors lower (Rust → foreign) but cannot be lifted: the derived `Lift` exists only to satisfy trait bounds, and its `try_read`/`try_lift` are `panic!("Can't lift flat errors")`. In an FFI callback that panic has nowhere to unwind to, so the host process aborts — and nothing catches it earlier, since the build, bindings generation, and Kotlin compilation all pass
+  - Applies to the error type of any `#[uniffi::export(with_foreign)]` trait or callback interface, since foreign code implements the method. `flat_error` is correct only for an error that travels Rust → foreign exclusively, e.g. `PublishError` in `livekit-datatrack/src/local/mod.rs`
+  - Give a host-thrown error a single `Failed { reason: String }` variant plus `From<uniffi::UnexpectedUniFFICallbackError>`, so an undeclared exception surfaces as an error rather than aborting — see `PacketDeliveryError` in `livekit-uniffi/src/data_stream/common.rs`
 
 ## Feature combinations
 

livekit-datatrack/src/e2ee.rs

@@ -33,19 +33,35 @@ pub struct EncryptedPayload {
 /// An error indicating a payload could not be encrypted.
 #[derive(Debug, Error)]
 #[cfg_attr(feature = "uniffi", derive(uniffi::Error))]
-#[cfg_attr(feature = "uniffi", uniffi(flat_error))]
 pub enum EncryptionError {
-    #[error("Encryption failed")]
-    Failed,
+    #[error("Encryption failed: {reason}")]
+    Failed { reason: String },
+}
+
+// Required because foreign code implements `EncryptionProvider::encrypt`: an exception that is
+// NOT an `EncryptionError` surfaces through this catch-all rather than aborting.
+#[cfg(feature = "uniffi")]
+impl From<uniffi::UnexpectedUniFFICallbackError> for EncryptionError {
+    fn from(error: uniffi::UnexpectedUniFFICallbackError) -> Self {
+        Self::Failed { reason: error.reason }
+    }
 }
 
 /// An error indicating a payload could not be decrypted.
 #[derive(Debug, Error)]
 #[cfg_attr(feature = "uniffi", derive(uniffi::Error))]
-#[cfg_attr(feature = "uniffi", uniffi(flat_error))]
 pub enum DecryptionError {
-    #[error("Decryption failed")]
-    Failed,
+    #[error("Decryption failed: {reason}")]
+    Failed { reason: String },
+}
+
+// Required because foreign code implements `DecryptionProvider::decrypt`: an exception that is
+// NOT a `DecryptionError` surfaces through this catch-all rather than aborting.
+#[cfg(feature = "uniffi")]
+impl From<uniffi::UnexpectedUniFFICallbackError> for DecryptionError {
+    fn from(error: uniffi::UnexpectedUniFFICallbackError) -> Self {
+        Self::Failed { reason: error.reason }
+    }
 }
 
 /// Provider for encrypting payloads for E2EE.

livekit/src/room/e2ee/data_track.rs

@@ -37,7 +37,7 @@ impl dt::EncryptionProvider for DataTrackEncryptionProvider {
         let encrypted = self
             .manager
             .encrypt_data(payload.into(), &self.sender_identity, key_index)
-            .map_err(|_| dt::EncryptionError::Failed)?;
+            .map_err(|e| dt::EncryptionError::Failed { reason: e.to_string() })?;
 
         debug_assert_eq!(
             encrypted.key_index as u32,
@@ -46,8 +46,12 @@ impl dt::EncryptionProvider for DataTrackEncryptionProvider {
             );
 
         let payload = encrypted.data.into();
-        let iv = encrypted.iv.try_into().map_err(|_| dt::EncryptionError::Failed)?;
-        let key_index = encrypted.key_index.try_into().map_err(|_| dt::EncryptionError::Failed)?;
+        let iv = encrypted.iv.try_into().map_err(|iv: Vec<u8>| dt::EncryptionError::Failed {
+            reason: format!("unexpected IV length: {}", iv.len()),
+        })?;
+        let key_index = encrypted.key_index.try_into().map_err(|e| {
+            dt::EncryptionError::Failed { reason: format!("key index out of range: {e}") }
+        })?;
 
         Ok(dt::EncryptedPayload { payload, iv, key_index })
     }
@@ -79,7 +83,9 @@ impl dt::DecryptionProvider for DataTrackDecryptionProvider {
                 payload.key_index as u32,
                 &sender_identity,
             )
-            .ok_or_else(|| dt::DecryptionError::Failed)?;
+            .ok_or_else(|| dt::DecryptionError::Failed {
+                reason: "the E2EE manager could not decrypt the payload".to_owned(),
+            })?;
         Ok(Bytes::from(decrypted))
     }
 }