Skip to content

iOS: notify the ADM observer when an enable operation rolls back after will-enable - #270

Open
hiroshihorie wants to merge 1 commit into
m144_releasefrom
hiroshi/adm-enable-rollback-compensation
Open

hiroshihorie wants to merge 1 commit into
m144_releasefrom
hiroshi/adm-enable-rollback-compensation

Conversation

@hiroshihorie

@hiroshihorie hiroshihorie commented Jul 10, 2026 •

Copy link
Copy Markdown
Member

Problem

OnEngineWillEnable runs before permission and category checks, node configuration, and engine startup. If a later step fails, rollback never notifies the observer. Observers that configure or activate the audio session in willEnable can therefore retain resources for an engine state that was never applied.

Change

After a successful OnEngineWillEnable, register a rollback action that calls OnEngineDidDisable with the previous state. This covers both device and manual rendering paths. The result is ignored because rollback cannot be cancelled.

OnEngineDidDisable may now represent an attempted enable returning to the previous state, not only a completed disable.

Testing

Built framework_objc for an arm64 iOS device. Reproduced by enabling input with an incompatible playback-only category and verified that rollback now notifies the observer.

…able

OnEngineWillEnable is invoked before the fallible parts of an enable
operation: permission and category checks, node configuration, and
engine start. When any of those failed, the rollback replayed only the
constructive engine actions and never told the observer, so an observer
that configured and activated the audio session for the enable was left
holding an activation for an engine state that never materialized. It
leaked until the next retry or stop.

Push a rollback action right after a successful will-enable that fires
OnEngineDidDisable with the previous engine state. Existing observers
already implement did-disable as the release edge, so they get correct
compensation without adopting a new callback. The result is ignored
since the rollback itself cannot be aborted. Applies to both the device
and manual rendering paths.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes an iOS observer lifecycle gap where OnEngineWillEnable can succeed but a later enable step fails, causing the engine to roll back without notifying the ADM observer—potentially leaking audio session activation in observers that acquire resources in willEnable.

Changes:

  • Add a rollback action immediately after successful OnEngineWillEnable that notifies the observer via OnEngineDidDisable with the previous engine state when a later enable step fails.
  • Apply the same rollback-notification behavior to both manual rendering and device rendering paths.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +1855 to +1859
if (observer_ != nullptr) {
LOGW() << "Enable rolled back after OnEngineWillEnable, notifying observer (Manual)";
observer_->OnEngineDidDisable(engine_manual_input_, state.prev.IsOutputEnabled(),
state.prev.IsInputEnabled());
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth doing?

Comment on lines +2297 to +2301
if (observer_ != nullptr) {
LOGW() << "Enable rolled back after OnEngineWillEnable, notifying observer";
observer_->OnEngineDidDisable(engine_device_, state.prev.IsOutputEnabled(),
state.prev.IsInputEnabled());
}
@hiroshihorie
hiroshihorie requested a review from pblazej July 15, 2026 17:06
hiroshihorie added a commit that referenced this pull request Nov 17, 2026
Supersedes #305, #306 and #309 (closed). #310 is a separate change.

## Problem

`ModifyEngineState` applies an engine transition step by step, rolls
back on any error, and commits the new state only when every step
succeeds. The engine observer hooks did not fit that model in two ways.

- Setup hooks could acquire without a release. When an enable failed
after a successful `OnEngineWillEnable`, or a create rolled back after a
successful `OnEngineDidCreate`, the observer was never told, so whatever
it acquired stayed held.
- Teardown hooks could roll back what cannot be undone.
`OnEngineDidStop`, `OnEngineDidDisable` and `OnEngineWillRelease` run
after `[engine stop]`, and the stop step registers no undo. An error
from them rolled the transition back with the engine already stopped, so
the committed state still said running. A later start saw no change and
never ran the engine, and an interruption end never restarted it.

## Change

The contract, documented in `api/audio/audio_device.h` and
`RTCAudioDeviceModule.h`:

1. Setup hooks (`OnEngineDidCreate`, `OnEngineWillEnable`,
`OnEngineWillStart` and the connect hooks) can fail the operation. A
non-zero result rolls it back and reaches the caller.
2. A setup hook that succeeded gets its release when the operation rolls
back. `OnEngineDidDisable` follows `OnEngineWillEnable`, and
`OnEngineWillRelease` follows `OnEngineDidCreate`.
3. Teardown hooks (`OnEngineDidStop`, `OnEngineDidDisable` and
`OnEngineWillRelease`) cannot fail the operation. A non-zero result is
logged and the operation completes.

One commit per rule:

- `68ac34a269` and `f92becad78`: will-enable compensation, port of #270
with its review follow-ups (previously #305).
- `9dc7a011fa`: did-create compensation (previously #306).
- `f300557860`: teardown errors are only logged, in the device and
manual rendering paths. Covers the interruption begin case of #309.

## Behavior change

A teardown hook error no longer reaches the caller. The Swift SDK's
`observerFail` audio test expects `stopLocalRecording()` to throw on a
failing `engineDidStop` and needs a matching update. React Native apps
whose JS did-stop handler throws get a log line instead of an error.

## Notes for review

- Not covered yet: an engine start failure after a successful
`OnEngineWillStart` still gets no `OnEngineDidStop`. The fault matrix
cannot inject a start failure, and current observers hold nothing from
will-start.
- #310 (double start at interruption end) and the interruption events
are separate changes and merge cleanly with this.

## Testing

- `clang -fsyntax-only` of `audio_engine_device.mm` and
`RTCAudioDeviceModule.mm` for macOS and iOS: no errors. The one iOS
warning is a pre-existing deprecation in `api/audio_options.h`.
- Fault injection matrix on device (iPhone 17 Pro Max, iOS 27),
apple-audio-lab `RollbackFaultMatrixTests`. A probe at the head of the
Swift SDK observer chain fails one of eight hooks once during one of
eight engine operations (capture start and stop, engine availability off
and on, interruption begin and end, mute and unmute in restart mute
mode). Each case then checks that bringing capture up runs the engine,
that taking it down stops it, and that every successful setup hook got
its release back at idle.
- Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11: 22 of 26
cases violate. 12 are setup failures that leak an acquire, 10 are
teardown failures that leave the engine stopped while the state says
running.
  - #306, which includes #305: 10 violations, all on the teardown path.
- Both numbers above predate the probe change below, which only affects
the three `willRelease` rows.
- A prototype of the teardown rule on top of #306 cleared the teardown
violations, except three that came from the probe itself (it failed
`willRelease` without forwarding it, which the probe now does).
  - This head: 0 of 26 cases violate.
- Other lab suites on this head, same device:
- Rolled back enable tests pass, including the did-disable order and the
release of the engine created for the failed enable.
- The #309 repro passes. A did-stop that fails at an interruption begin
no longer drops the interruption, and the end restarts the engine.
- A did-stop that fails on an app requested stop no longer throws, and
the next start runs the engine.
  - Interruption path and processing seed tests pass.
- The double start repros still hit `Check failed:
configuration_observer_ == nullptr` on this head, as expected without
#310.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants